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TECHNICAL FIELD 

This invention relates generally to the field of computer systems, and, more particularly, 
to the use of input devices with software applications. 



20 BACKGROUND 

Various input devices are available to permit a computer user to communicate with a 
computer. A typical personal computer offers input devices such as a keyboard and a mouse. 
Numerous other devices are available, such as drawing pads, joysticks, and steering wheels (for 
use with driving games). These devices can be connected to a computer, and they permit the user 
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to communicate information to the computer; the information communicated instructs software 
applications running on the computer to perform specified actions. Ideally, a computer user 
would be able to load a software application, connect an appropriate device to the computer, and 
the device and software would work together naturally. This ideal, however, has not been realized 
5 in prior systems. 

In order for a device to work with a given software application, there must be a defined 
relationship between the controls on the device and actions that the software performs, but there 
are few standards governing the way in which this relationship is defined. Traditionally, software 
developers design software applications to support the most common devices and provide a 

10 device mapping control panel for those users who own other devices. This approach, however, 
has drawbacks: A software developer who wants to design an application to work well with many 
devices must know what controls are available on each device (e.g., buttons, levers, etc.) and how 
the device notifies the computer system of operational events (e.g., an input of 1001 signifies the 
pressing of a button). Additionally, the software developer must make design decisions as to 

1 5 which devices the software will support, and, on those devices that will be supported, how the 
controls will map to the actions that the software performs, which is a labor-intensive process for 
the software developer. Moreover, if a user owns an unsupported device, the user must generally 
resort to mapping the unsupported device manually by referring to generic pictures and tables in 
an application's manual and using the device mapping control panel provided with the 

20 application, which is a notoriously difficult process. 

Some input device manufacturers address the problem of ensuring that specific 
applications work well with the device by supplying a software component with the device that 
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dynamically reconfigures the device based on guesses as to what actions the application expects 
the device to support. Some manufacturers of devices with newer features provide filters to 
accommodate existing applications; frequently, these filters simulate keyboard presses or mouse 
movements for games that do not recognize enhanced features of the new device. Alternatively, 
5 some devices are supplied with mapping software that detects the presence of certain applications 
on the system and configures the device to work better with those applications. These ad hoc 
approaches, however, are error prone, may result in a relationship between device controls and 
software actions that feels unnatural to the user, and can only provide support for applications 
the device manufacturer knows about and chooses to support. 
10 In view of the foregoing, there is a need for a system that overcomes the drawbacks of the 

prior art. 

SUMMARY 

The system of the present invention includes a Mapper Application Program Interface 
15 (API), which links controls on input devices with actions that a software application performs. 
The Mapper API uses vocabularies of semantics, called "genres," where the semantics in each 
genre are appropriate for a particular category of applications, such as driving games or flight 
simulation games. For each input device, a correlation is made between the device's controls and 
semantics selected from a genre. Also, for each software application, a correlation is provided 
20 between the application's actions and semantics selected from a genre. The Mapper API creates 
a mapping between device controls and software actions by identifying an input device that 
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supports the software's genre and by connecting, as closely as possible, each control on the 
device with a software action that is correlated with the same semantic. 

Game applications exemplify the system's use. For example, there may be a "driving 
game" genre. Each semantic in the driving game genre represents an abstract action that a driving 
5 game may be able to perform, such as "steer," "accelerate," and "decelerate." A steering wheel 
device may correlate the "steer" semantic with turning the steering wheel, and the "accelerate" 
and "decelerate" semantics with the right and left pedals. A driving game application may 
correlate the "steer," "accelerate," and "brake" semantics with the game actions of turning, 
speeding up, and slowing down, respectively. The Mapper API maps each device control into 
10 the game action associated with the same semantic. The Mapper API uses these correlations to 
map device controls into software actions; for example, the steering wheel maps to the action of 
turning the car, and the right and left pedals map to the actions of speeding up and slowing down 
the car. 

The system may include several genres, where the different genres are appropriate for 
15 different types of applications. For example, in addition to the driving game genre described 
above, there could be a flight-simulation genre and a computer-aided design (CAD) genre. 
Devices may specify which genres they work well with and may provide a correlation between 
their controls and the semantics from each such genre. An application, on the other hand, can 
specify which genre the application falls into, or may specify various genres, representing 
20 different contexts within the application. For example, a game may start out in a driving game 
genre while a character drives to the location of a mission; later, the game may switch to a first- 
person fighter genre for when the character gets out of the car and moves around fighting targets. 
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The mapping created may be used by an input device manager, which translates 
notification of device events (such as the pressing of a button on a joystick) into the application's 
input dialect while the application executes. Alternatively, the Mapper API may provide the 
mapping directly to the application, which then receives event notifications directly from the 
5 various input devices and uses the mapping to perform a particular action upon receiving 
notification of a corresponding device event, as specified in the mapping. 

The Mapper API has several methods that can be used by the application program. For 
example, EnumDevicesBySemantics enumerates installed input devices on the system according 
to the genre specified by the application. Additionally, BuildActionMap creates the mapping for 
10 actions to controls for a selected device. SetActionMap sets an action map to the selected device, 
and saves the map for future use if settings have been changed. 

Other features of the invention are described below, 

BRIEF DESCRIPTION OF THE DRAWINGS 

15 The foregoing summary, as well as the following detailed description, is better 

understood when read in conjunction with the appended drawings. For the purpose of illustrating 
the invention, there is shown in the drawings exemplary constructions of the invention; however, 
the invention is not limited to the specific methods and instrumentalities disclosed. In the 
drawings: 

20 Figure 1 is a block diagram representing a computer system in which aspects of the 

invention may be incorporated. 
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Figure 2 is a block diagram showing the use of an input device mapper with input devices 
and software applications. 

Figure 3 is a block diagram showing a sample control-semantic correlation and its 
structure. 

5 Figure 4 is a block diagram showing a sample action-semantic correlation and its 

structure. 

Figure 5 is a block diagram showing a sample mapping created by an input device 
mapper. 

Figure 6 is an image of an input device with action labels, as displayed by an input device 
10 mapper. 

Figure 7 is a flowchart illustrating the process by which an input device mapper maps 
controls to actions; 

Figure 8 is a block diagram showing the use of a mapping created by an input device 
mapping. 

1 5 Figure 9 is a block diagram of a Microsoft Component Object Model software component 

that can be used to implement the present invention. 

Figure 10 is a system diagram showing the Mapper API as an interface to expose 
operating system resources. 

Figure 1 1 is a diagram showing the Mapper API methods according to the invention. 
20 Figure 12 is an exemplary illustration of a user interface (UI) used with the present 

invention. 
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Figure 13 is a flowchart of a method for determining the most suitable input devices to 
use with an application. 

Figure 14 is a flowchart of a method for configuring the user interface. 

Figure 15 is a flowchart of a method for building a control-to-action mapping for a 
selected input device. 

Figure 16 is a flowchart of a method for setting the action map subsequent to building. 
Figure 17 is a flowchart of a method for allowing applications to configure the user 
interface. 

DETAILED DESCRIPTION 
Overview 

The variety of software applications and input devices available gives consumers 
increasingly large choices as to the applications and devices to use with a computer. This variety 
comes at the expense of compatibility, as not all applications and devices are configured to work 
together. Ideally, a computer user should be able to load an application, such as a game, connect 
an appropriate input device, and have the application and device work together in a manner that 
feels natural to the user, thus allowing true "plug and play" capability. 

Computer Environment 

Fig. 1 and the following discussion are intended to provide a brief general description of 

a suitable computing environment in which the invention may be implemented. Although not 
required, the invention will be described in the general context of computer-executable 
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instructions, such as program modules, being executed by a computer, such as a client 
workstation or a server. Generally, program modules include routines, programs, objects, 
components, data structures and the like that perform particular tasks or implement particular 
abstract data types. Moreover, those skilled in the art will appreciate that the invention may be 
5 practiced with other computer system configurations, including hand-held devices, multi- 
processor systems, microprocessor-based or programmable consumer electronics, network PCs, 
minicomputers, mainframe computers and the like. The invention may also be practiced in 
distributed computing environments where tasks are performed by remote processing devices that 
are linked through a communications network. In a distributed computing environment, program 

10 modules may be located in both local and remote memory storage devices. 

As shown in Fig. 1, an exemplary system for implementing the invention includes a 
general purpose computing device in the form of a conventional personal computer 20 or the like, 
including a processing unit 21, a system memory 22, and a system bus 23 that couples various 
system components including the system memory to the processing unit 21 . The system bus 23 

15 may be any of several types of bus structures including a memory bus or memory controller, a 
peripheral bus, and a local bus using any of a variety of bus architectures. The system memory 
includes read-only memory (ROM) 24 and random access memory (RAM) 25. A basic 
input/output system 26 (BIOS), containing the basic routines that help to transfer information 
between elements within the personal computer 20, such as during start-up, is stored in ROM 24. 

20 The personal computer 20 may further include a hard disk drive 27 for reading from and writing 
to a hard disk, not shown, a magnetic disk drive 28 for reading from or writing to a removable 
magnetic disk 29, and an optical disk drive 30 for reading from or writing to a removable optical 
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disk 31 such as a CD-ROM or other optical media. The hard disk drive 27, magnetic disk drive 
28, and optical disk drive 30 are connected to the system bus 23 by a hard disk drive interface 
32, a magnetic disk drive interface 33, and an optical drive interface 34, respectively. The drives 
and their associated computer-readable media provide non-volatile storage of computer readable 
5 instructions, data structures, program modules and other data for the personal computer 20. 
Although the exemplary environment described herein employs a hard disk, a removable 
magnetic disk 29 and a removable optical disk 31, it should be appreciated by those skilled in the 
art that other types of computer readable media which can store data that is accessible by a 
computer, such as magnetic cassettes, flash memory cards, digital video disks, Bernoulli 

10 cartridges, random access memories (RAMs), read-only memories (ROMs) and the like may also 
be used in the exemplary operating environment. 

A number of program modules may be stored on the hard disk, magnetic disk 29, optical 
disk 31, ROM 24 or RAM 25, including an operating system 35, one or more application 
programs 36, other program modules 37, program data 38, and an input device mapper 39. A user 

15 may enter commands and information into the personal computer 20 through input devices such 
as a keyboard 40, a pointing device 42, a drawing pad 65, or a game controller such as driving 
game controller 66. Other input devices (not shown) may include a microphone, joystick, game 
pad, satellite disk, scanner or the like. These and other input devices are often connected to the 
processing unit 21 through a serial port interface 46 that is coupled to the system bus, but may 

20 be connected by other interfaces, such as a parallel port, game port, universal serial bus (USB), 
or a 1394 high-speed serial port. A monitor 47 or other type of display device is also connected 
to the system bus 23 via an interface, such as a video adapter 48. In addition to the monitor 47, 
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personal computers typically include other peripheral output devices (not shown), such as 
speakers and printers. 

The personal computer 20 may operate in a networked environment using logical 
connections to one or more remote computers, such as a remote computer 49. The remote 
5 computer 49 may be another personal computer, a server, a router, a network PC, a peer device 
or other common network node, and typically includes many or all of the elements described 
above relative to the personal computer 20, although only a memory storage device 50 has been 
illustrated in Fig. 1. The logical connections depicted in Fig. 1 include a local area network 
(LAN) 5 1 and a wide area network (WAN) 52. Such networking environments are commonplace 
J5J 1 0 in offices, enterprise-wide computer networks, Intranets and the Internet. 
~C\ When used in a LAN networking environment, the personal computer 20 is connected 

s to the local network 51 through a network interface or adapter 53. When used in a WAN 

SI networking environment, the personal computer 20 typically includes a modem 54 or other 

J: means for establishing communications over the wide area network 52, such as the Internet. The 

15 modem 54, which may be internal or external, is connected to the system bus 23 via the serial 
port interface 46. In a networked environment, program modules depicted relative to the personal 
computer 20, or portions thereof, may be stored in the remote memory storage device. It will be 
appreciated that the network connections shown are exemplary and other means of establishing 
a communications link between the computers may be used. 



20 
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liiput Device Mapper 

Fig. 2 depicts the use of an input device manager in accordance with the invention. Input 

device mapper 39 is a software module that provides an interface between application programs 
36 and input devices, such as devices 42, 65, 66, and 67. Input device mapper 39 could be a 
5 component of an operating system running on computer 20, such as operating system 35, or a 
stand-alone software module which runs on an operating system, as shown in Fig. 2. 

Input device mapper 39 is associated with several genres, such as genres 211-213. A 
genre is a semantic vocabulary that encapsulates the common input elements among applications 
falling into a broad category. A semantic is a label that expresses a behavior that an application 

1 0 exhibits upon operation of a control. Input device mapper 39 is associated with at least one genre; 
preferably, input device mapper 39 is associated with several genres. The genres associated with 
an input device mapper may be publicized so that input device manufacturers and software 
developers can use input device mapper 39 in the manner described below to allow devices and 
software to work together. 

15 In Fig. 2, genre 21 1 is an example driving game genre (corresponding to example genre 

1 in the Examples section below), genre 212 is an example flight simulator genre (corresponding 
to example genre 2 in the Examples section below), and genre 213 is an example computer-aided 
design (CAD) genre (corresponding to example genre 8 in the Examples section below). Input 
devices 65, 66, 67, and 42 provide input device mapper 39 with correlations between their 

20 controls and the semantics of genres 211-213, called "control-semantic" correlations 221-225 
(abbreviated "C-S correlation"). C-S correlation 221, which is shown in detail in Fig. 3, 
correlates the controls on driving game controller 66 with semantics chosen from driving 
simulation genre 211. Joystick 67 is appropriate for use with both driving simulation applications 
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and flight simulation applications. Therefore, joystick 67 provides two different C-S correlations; 
C-S correlation 222 provides a link to the controls on joystick 67 with driving simulation genre 
21 1, and C-S correlation 223 provides a link to the controls on joystick 67 with flight simulator 
genre 212. Mouse 42 and drawing pad 65 provide C-S correlations 224 and 225, respectively, 
5 between their controls and CAD genre 213. A device may provide additional C-S correlations 
for specific purposes. For example, the manufacturer of driving game controller 66 may provide 
C-S correlation 221 which is appropriate for the driving simulation genre generally, but may also 
provide additional C-S correlations (not shown), which refine C-S correlation 221 for use with 
particular driving games. Each C-S correlation may specify the applications (e.g., the "XYZ" 

10 driving game) or classes of application (e.g., all applications in a driving simulation genre) with 
which it may be used. Applications 36a and 36b provide input device mapper 39 with 
correlations between actions that they perform and genres 211-213, called "action-semantic" 
correlations 231-233 (abbreviated U A-S correlation"). Driving game application 36a provides A-S 
correlation 231, which is shown in detail in Fig. 4, between its actions and semantics selected 

15 from driving simulation genre 211. Architectural design application 36b provides an A-S 
correlation between its actions and CAD genre 213. In addition to A-S correlation 231, driving 
game application 36a also provides A-S correlation 232 between its actions and flight simulator 
genre 212. Providing two different A-S correlations for a single application is appropriate when 
the application has two different phases that require different usage of the controls. 

20 Input device mapper 39 receives C-S correlations 221-225 and A-S correlations 231-233. 

Input device mapper 39 creates a mapping for each application program 36a, 36b, on computer 
20. For example, in order to create mapping 220 for driving game application 36a, input device 
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mapper 39 first selects an appropriate device for the driving game genre, by determining which 
devices have a C-S correlation for the driving simulation genre. If there is more than one device 
having a C-S correlation for driving simulation genre 211, such as driving game controller 66 and 
joystick 67, then input device mapper 39 selects one of these devices. The selection may be made 
5 in various ways, for example by selecting the first appropriate connected device that input device 
mapper 39 locates, or by consulting a database of preferred devices for each genre. For example, 
input device mapper 39 selects game controller 66 because it is the first device that it locates 
which supports driving simulation genre 211. Once the device is selected, input device mapper 
39 uses C-S correlation 221 and A-S correlation 231 to map controls on game controller 66 into 
10 actions that driving game application 36a performs. Input device mapper 39 may create the 
mapping by performing a simple matching (i.e., by referring to C-S correlation 221 and A-S 
correlation 231 and linking each control with an action that is correlated with the same semantic), 
or it may take into account user preferences or overrides, as discussed below in the text 
accompanying Fig. 6. 

15 Input device mapper may create a second mapping (not shown) for a different phase of 

an application that requires controls to be used in a different context, such as the role-playing 
phase of driving simulation game 36a. That mapping is created by selecting an appropriate device 
for the role-playing genre to map the controls on joystick 67 into the actions for the role-playing 
phase of game application 36a. Some applications change context frequently, such as a baseball 

20 game application, where the context of the controls is different for pitching than it is for batting. 

Fig. 3 depicts the detail of sample C-S correlation 221. Controls 301 represent controls 
on driving game controller 66. Semantics 302 are semantics chosen from driving simulation 
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genre 21 1. C-S correlation 221 links controls 301 with semantics 302. In the example depicted 
by Fig. 3, "Trigger 1" on game controller 66 is associated with the semantic "FIRE", "Button 1" 
is associated with the semantic "SHIFT UP", etc. 

Fig. 4 depicts the detail of sample A-S correlation 231. Actions 401 represent actions that 
5 driving game application program 236 can perform at the user's request. Semantics 402 are 
semantics chosen from driving simulation genre 211. In the example depicted by Fig. 4, the 
action performed by the driving game described as "turn left or right" is associated with the 
semantic "STEER", "speed up" is associated with the semantic "ACCELERATE", etc. 

Fig. 5 depicts a sample mapping 220 created by input device mapper 39, which links the 

1 0 controls on game controller 66 with actions performed by driving game application 36a. Controls 
301 are correlated with semantics, as defined in C-S correlation 221. The semantics are correlated 
with software actions 401 , as defined in A-S correlation 23 1 . In the example, "trigger 1" 502 on 
game controller 66 is correlated with the semantic "FIRE" 503, which, in turn, is correlated with 
the software action "fire machine guns" 504. 

1 5 The detail of an entry in the mapping is shown in items 511-513. Each entry contains a 

controller code 511, an application code 512, and a label 513. The controller code 51 1 is the data 
that an input device generates when a particular control has been operated. For example, game 
controller could signify that trigger 1 has been pressed by generating the number "1002." The 
application code 512 is the item of input that an application expects to receive as an instruction 

20 to perform a particular action. For example, the input "64379" could instruct driving game 
application 36a to fire machine guns. Label 513 is a text string provided by application program 
36a, which is a plain language description of the action that application program 36a will perform 
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upon receiving application code 512 as its input. For example, "fire machine guns" is a label 
describing the action that will be performed by driving game application 36a when trigger 1 is 
depressed. The labels are helpful for displaying a graphic representation of the mapping, as 
described below in the text accompanying Fig. 6. 
5 Fig. 5 also shows a control labeled "button 2" 505 on game controller 66, which is 

correlated with the semantic "TALK" 506, which might be appropriate for the action of operating 
a two-way radio to talk with other drivers. This correlation means that button 2 would be mapped 
to an action correlated with the "TALK" semantic in an application that has such an action. 
Driving game application 36a, however, does not have an action correlated with the "TALK" 
1 0 semantic; therefore, button 2 on game controller 66 does not map to any action in driving game 
application 36a. 

It will also be observed in Fig. 5 that mapping 220 uses a semantic "DASHBOARD" 507, 
which is correlated with the action in driving game application 36a of changing the dash display, 
and it will also be observed that game controller 66 does not have a control correlated with the 

1 5 "DASHBOARD" semantic. A feature of input device mapper 39 is that it provides an application 
with the model that all of the defined semantics in a genre are supported in any computer system 
on which the application may be running, such as computer 20. For example, even though game 
controller 66 does not have a control correlated with the "DASHBOARD" semantic, driving 
game 36a may still correlate its "change dash display" action with the semantic 

20 "DASHBOARD," and input device mapper 39 will locate an appropriate auxiliary input for that 
action. In mapping 220, auxiliary input 501 is selected by input device mapper 39 to implement 
the "DASHBOARD" semantic. Auxiliary input 501 may be a key on keyboard 40, an unused 
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control on game controller 66 such as control 505, a pop-up menu that the user can control with 
pointing device 42, or any other mechanism by which the user can communicate with computer 
20. 

The genres may be defined such that some semantics must be mapped to the primary 
5 input device selected by input device mapper 39 and may not be mapped to an auxiliary input 
outside of that device. For example, in the genres provided below in the Examples section, 
controls are divided into the categories "priority 1" and "priority 2." A priority 1 control is a 
control that must be mapped to the primary input device and may not be implemented by an 
auxiliary input. A priority 2 control is a control that may be implemented on the primary input 

10 device, if a control is available. For example, in the genre "driving sim without weapons" shown 
in below in the Examples section, steering is a priority 1 control, so the "steer" semantic must 
be implemented on the primary input device selected by input device mapper 39, such as game 
controller 66. However, "dashboard" is a priority 2 control, so it may be implemented by any type 
of auxiliary input. Some other controls, which may be designated as "priority 3," are never 

15 implemented by the device used for the mapping, and therefore the genres do not define 
semantics to correlate with these controls. For example, a game application may provide a pop-up 
menu to change the background color of the screen, select the background music accompanying 
the game, select weapons to be carried, etc. Because no semantics are defined for priority 3 
functions, they are either implemented by the application through explicit manipulation of the 

20 controller code 511 or by requesting a generic mapping from the input device mapper 39. 

It is also possible for a user to affect a mapping created by input device mapper 39, either 
by providing a set of preferences for input device mapper 39 to take into account in creating the 
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mapping, or by modifying a mapping after it has been created. For example, a user may create 
a set of preferences specifying that button 1 on game controller 66 should always map to the 
semantic "HONK HORN" in every application falling into a driving simulation genre. A user 
may also modify a mapping that has been created: Input device mapper 39 may provide the user 

5 with a display showing the device controls that have been mapped to particular software actions, 
and may permit the user to change the mapping. Fig. 6 depicts such a display, as might appear 
for joystick 67. The manufacturer of joystick 67 may provide a bitmap image or 3D model of the 
device, with blank text fields that are filled in with data from the application. The data is 
provided by the application as part of the A-S correlation in the form of text strings; the 

1 0 application may provide a text string label for each action, and the labels may be displayed with 
an image of the device. For example, text field 601 is filled in with the text "enable cloaking 
device," which indicates that button 602 is mapped to a cloaking device action in the game 
application. This text string was provided to input device mapper 39 in an A-S correlation and 
becomes part of the mapping, as depicted in elements 51 1-513 in Fig. 5. The user can create a 

1 5 custom mapping, for example by using a mouse 42 to rearrange the labels on the displayed image 
of the device. If the user creates a custom mapping, input device mapper 39 may interpret the 
user's changes as the expression of a set of preferences. For example, if a user uses the display 
depicted in Fig. 6 to modify the mapping of joystick 67 into the actions for a game in the first- 
person genre, input device mapper 39 may interpret the user's choice as a general preference that 

20 joystick 67 should work similarly with all games in first-person genres (i.e., that button 602 
should enable a cloaking device in any first-person game that offers a cloaking device). The 
user's preferences may be stored in a file or database for future use by the user. Additionally, 
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storing the preferences in a file or database permits the preferences to be easily ported from 
computer 20 to any other machine on which input device mapper 39 has been implemented, thus 
permitting consistent mappings across several machines. 

5 Use of the Innut Device Mapper 

Fig. 7 is a flowchart showing an example use of an input device mapper in accordance 

with the present invention, and the steps to initiate its use. As shown in Fig. 6 and described in 
detail below, a device and an application both undergo a setup phase, in which they pass their 
respective C-S and A-S correlations to an input device mapper; the application program then 

1 0 receives and processes input in accordance with the mapping. 

Steps 701 through 704 relate to the setup of an application program for use with input 
device mapper 39. An application program, such as driving game application 36a, begins 
execution at step 701. At step 702, the application creates an array correlating actions with 
semantics. For example, application 36a could create an array representing A-S correlation 231. 

1 5 The array created at step 702 is passed to input device mapper 39 at step 703 . 

One method of representing A-S correlation 231 in the array created as step 702 is to 
assign a unique value to each action and to each semantic. For example, the semantics in genre 
211, which are used in A-S correlation 231 and C-S correlation 221, may be assigned unique 
values as follows: 1 represents "STEER", 2 represents "ACCELERATE", etc. In a programming 

20 environment that supports symbolic constants, such as C++, it is convenient to represent the 
values as symbols. Input device mapper 39 may define the set of available genres and assign 
symbolic constants to each semantic, which may be exported to users of input device mapper 39 
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in a header file. Similarly, unique values may be assigned to each action that application program 
36a performs, which may also be represented by symbolic constants in an appropriate 
programming environment. The array created at step 702 then contains a sequence of ordered 
tuples, where each tuple includes, in a defined order, a value representing an action performed 
5 by the application, and a value representing a semantic correlated with that action. 

Steps 705 and 706, which relate to the setup of a device for use with an input device 
mapper in accordance with the invention, take place asynchronously with respect to steps 701, 
702, and 703. For an input device connected to computer 20, an array is created at step 705 
correlating the controls on the device with semantics from a particular genre. For example, an 
1 0 array may be created representing C-S correlation 22 1 , which correlates the controls on device 
66 with semantics chosen from genre 21 1. The C-S correlation may be represented in an array 
in a manner analogous to that used to represent an A-S correlation, as described above: unique 
values are associated with each control, and an array is constructed to contain a sequence of 
ordered tuples, where each tuple includes, in a defined order, a value representing a control and 
1 5 a value representing a semantic correlated with the control. When multiple C-S correlations exist 
for a given device, they may be represented in multiple arrays. The array(s) created at step 705 
is (are) passed to input device mapper 39 at step 706. Optionally, any user preferences that have 
been specified may also be passed to input device mapper 39 in an appropriate format at step 706. 
The creation of the array at step 705 may take place long before application 36a begins 
20 executing, or at any time prior to steps 704 and 706. For example, the supplier of game controller 
66 may create C-S correlation 221 at the time game controller 66 is designed, and supply an array 
representing C-S correlation 221 along with game controller 66 on a medium such as magnetic 
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disk 29 or optical disk 31; this array can then be passed to input device mapper 39 at step 706 by 
loading it into computer 20 through magnetic drive 28 or optical drive 30. Alternatively, game 
controller 66 may be known to the designer of input device mapper 39, in which case the array 
may be built into input device mapper 39. 

5 Step 704 takes place after steps 703 and 706 have been completed. After input device 

mapper 39 has received the arrays created at step 702 and the array created at step 705, it creates 
a mapping, such as mapping 220, by the process described above in the text accompanying Fig. 
5. After the mapping has been created, input device mapper 39 may provide mapping information 
to application program 36a at step 704. The mapping information provided may include 

1 0 information about which device control is correlated with each application-defined action. If the 
mapping is provided to application program 36a at step 704, then application program 36a can 
use the mapping to convert notifications of device events into actions that application program 
36a performs. Alternatively, instead of providing the mapping to application program 36a, the 
mapping may be provided to an input device manager, which is depicted in Fig. 8 and described 

1 5 below, which uses the mapping to translate device event notifications into input for application 
program 36a. In the case where an input device manager is used to translate device event 
notifications into application program input, it is not necessary to provide the mapping to 
application program 36a, in which case step 704 can be omitted. 

Following step 704, application program 36a begins its input loop 709, which comprises 

20 listening for input at step 707, processing the input at step 708, and returning to step 707 to listen 
for more input. When the mapping has been provided to application program 36a at step 704, 
application program 36a can use the mapping to process the input. In this case, application 
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program would receive notification of events on an input device, such as game controller 66, and 
would use the mapping to look up what actions to perform in response to a given event. 
Alternatively, when an input device manager is used, as depicted in Fig. 8 and discussed below, 
the input device manager translates each device event notification into an instruction to 
5 application program 36a to perform a particular action. In this case, application program 36a does 
not perform any lookup into the mapping in processing step 707; it simply follows instructions 
received from the input device manager. 

Fig. 8 shows an input device manager 801, which uses mapping 220 created by input 
device mapper 39 to provide communication between driving game application 36a and game 
1 0 controller 66. Input device manager 801 operates during execution of an application program, 
and uses a mapping to translate notification of input device events into commands to the 
application program. For example, in Fig. 8, input device manager 801 uses mapping 220, which 
is depicted in Fig. 5, to translate between events on game controller 66 and driving game 
application 36a. Driving game controller 66 sends input device manager 801 a data item 
15 signifying that an event has happened, such as the pressing of the right pedal. Input device 
manager 801 performs a lookup in mapping 220, and determines that the data received is 
correlated with the semantic "ACCELERATE," which, in turn, is correlated with the action 
"speed up." Input device manager 801 then sends into the input stream of driving game 
application 36a data representing an instruction to perform the "speed up" action. 
20 In addition to providing instructions to driving game application 36a, input device 

manager 801 may also provide other information including the duration of its operation, a 
timestamp for the operational event (e.g., button 1 was pressed at time = Tl, x-axis was moved 
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to position -32 at time = T2, etc.), or a parameter further describing the device event (e.g., in 
addition to data signifying that motion along the x-axis has occurred, input device manager 801 
may also provide data indicating the magnitude and direction of the motion, or data indicating 
the resulting position of the control). An application, such as driving game application 36a, may 
5 be interested in this information. For example, the firing of a weapon may become more rapid 
after trigger 1 has been depressed for more than one second. A different game application might 
cause a pinball cue or a slingshot to be pulled back further the longer a button has been 
depressed. 

It should also be noted that mappings are per device. That is, the application does not 
1 0 make a single call to obtain mappings for all devices. Rather, the application does one call per 
input device that the application intends to use. Input device manager 801 may receive event 
notifications from multiple devices, while reporting events from discrete devices in a consistent 
manner. By doing so, it allows an application to be controlled by various devices while allowing 
the application to view events without regard to the nature of the underlying device. For example, 
15 the auxiliary input used to implement the "change dash display" action correlated with the 
"DASHBOARD" semantic in driving game 36a could be the "D" key on keyboard 40 (not shown 
in Fig. 8). Input device manager 801 will receive notification that the "D" key on keyboard 40 
has been pressed, and will translate this notification into an instruction to driving game 
application 36a. The type of device from which of the input was created is transparent to 
20 application 36a, which knows only that it has received the instruction to perform the action 
correlated with the semantic "DASHBOARD." 
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When an application and a device are configured such that the application can instruct 
the device to perform certain actions, input device manager 801 can also use mapping 220 to 
convey these instructions from the application to the device. 

A further type of information that might be conveyed to input device manager 801 from 

5 an application is the application' s context, so that input device manager 80 1 can change the sense 
of the controls to match their use in the present phase of the game. For example, driving game 
36a may notify input device manager 801 when it has changed from the driving simulation genre 
to the role-playing genre, so that the use of the controls will be appropriate for the current phase 
of the game; as another example, a baseball game application may notify the input device 

1 0 manager when it changes from a batting context to a fielding context. Input device manager 801 
uses this information to look up the appropriate mapping information for the present context. 

It is noted that the foregoing examples have been provided merely for the purpose of 
explanation and are in no way to be construed as limiting of the present invention. While the 
invention has been described with reference to preferred embodiments, it is understood that the 

1 5 words which have been used herein are words of description and illustration, rather than words 
of limitations. Further, although the invention has been described herein with reference to 
particular means, materials and embodiments, the invention is not intended to be limited to the 
particulars disclosed herein; rather, the invention extends to all functionally equivalent structures, 
methods and uses, such as are within the scope of the appended claims. Particularly, while the 

20 invention has been described in terms of the use of a game controller with a game application, 
it is in no way limited to game hardware and software; on the contrary, it will be appreciated by 
those skilled in the art that the invention can be used with all types of software and input 
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hardware. Those skilled in the art, having the benefit of the teachings of this specification, may 
effect numerous modifications thereto and changes may be made without departing from the 
scope and spirit of the invention in its aspects. 



5 EXAMPLES 

The following are examples of genres that could be used with an input device mapper. 
The semantics in each genre are divided into "priority 1" semantics and "priority 2" semantics, 
which are described below: 



Genre 1: Combat Driving sim, with weapons 



10 Priority 1 Controls 

Semantic 

Steer 

Accelerate 



15 



Brake 

Weapons 

Fire 

Target 

Menu 



Description 
left /right 
faster / slower 
Brake 

select next weapon 

fires selected weapon 

selects next available target 

pause, show menu of priority 2 & 3 controls 



Priority 2 Controls 

20 Semantic 

Look 
View 



Description 

forward / right / backward / left 
cycle through view options 
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Down shift 



EXPRESS MAIL LABEL NO. EL696105267US 
Date of Deposit: May 14, 2000 



-25 



show device and controls 

select next dashboard / heads-up display option 

for voice communication 

select next higher gear 

select next lower gear Reverse from neutral 



Genre 2: Flving Sim, without weapons 



Priority 1 Controls 

Semantic 

Bank 

10 Climb /dive 

Throttle 
Brake 
Menu 

Priority 2 Controls 

15 Semantic 

Look 
Rudder 
View 
Display 
20 Flaps up 

Flaps down 
Toggle Gear 



Description 
bank ship left / right 
pitch up / down 
faster / slower 
brake 

pause, show menu of priority 2 & 3 controls 
Description 

forward or up / back or down / left / right 
turn ship left / right 

select next view (in the cockpit, behind plane, etc.) 
select next on-screen display options, maps, etc. 



Gear up / down 
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Press to talk voice communication 

Device displays input device and controls 

Genre 3: Role Playing 
Priority 1 Controls 



Semantic 


Description 


Move 


forward / back / left / right 


Get 


pick up and carry item 


Select Inventory 


select next inventory item 


Apply 


use selected inventory item 


Attack 




Cast 


cast spell 


Talk 


communicate 


Crouch 


crouch, climb down, swim down 


Jump 


jump, climb up, swim up 


Menu 


pause, show menu of priority 2 & 3 controls 



Priority 2 Controls 

Semantic Description 

Look forward or up / back or down / left / right 

usually maps to point of view ("POV") on devices that have one 

20 Map cycle through map options 

Display shows next on-screen display options, maps, etc. 

Press to talk voice communication (multi-player) 
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Rotate 
Device 

Genre 4: Hunting 

Priority 1 Controls 

5 Semantic 

Move 



Aim 
Fire 

Weapon 

Binoculars 

Call 

Map 

Special 

Menu 



turn body left / right 

displays input device and controls 



10 



15 



20 



Priority 2 Controls 

Semantic 

Look 



Display 
Press to talk 
Rotate 
Crouch 



Description 

move forward / backward / left / right - or - 
aim up / down / left / right 
toggle "Move" axis above between aim and move 
fire selected weapon 

select next weapon (cycle through options) 
look through binoculars 
make animal call 
view map 

do game special operation (rattle, eat) 
pause, show menu of priority 2 & 3 controls 

Description 

forward or up / back or down / left / right usually maps to 

POV on devices that have one 

shows next on-screen display options, maps, etc. 

voice communication (multi-player) 

turn body left / right 

crouch, climb down, swim down 
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Jump 
Device 



jump, climb up, swim up 
displays input device and controls 



Genre 5: Real Time Strategy 

Priority 1 Controls 

5 Semantic 

Scroll 



Select 

Instruct 

Apply 

Team 

Building 

Menu 



10 



15 



Priority 2 Controls 

Semantic 

Map 
Display 
Press to talk 
Device 



Description 

up / down / left / right 

Select unit / object / item 

cycle through instructions 

apply selected instruction 

select next team (cycle through all) 

select next building 

pause, show menu of priority 2 & 3 controls 
Description 

cycle through map options 
shows next on-screen display options, maps, etc. 
voice communication (multi-player) 
displays input device and controls 



Genre 6: Baseball 

20 Priority 1 Controls - batting 

Semantic Description 



Aim 



aim where to hit 
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rvrle, fhrouerh swing ontions 


Normal 


nnrmol c Yin Tier 
IlOlIIlal SWlIlg, 


Power 


swing lur iiic lciiuc 


Bunt 


bunt 


steal 


V»o^ ra Iaoco rntltlAT of fomf^t ff\ officii O nQCP 

nave oase runner aiicixipi iu &ica.i a uaow 


Burst 


nave oase runner iiivokc uuxoi ui opecu 


Slide 


have base runner slide into base 


Box 


Enter or exit batting box 


Menu 


pause, show menu of priority 2 & 3 controls 



Priority 2 Controls - hatting 
(none) 

Priority 1 Controls - pitching 



Semantic 


Description 


Aim 


aim where to pitch 


Select 


cycle through pitch selections 


Pitch In 


throw pitch into strike zone 


Pitch Out 


throw pitch outside of strike zone 


Base 


select base to throw to 


Throw 


throw to base 


Catch 


catch hit ball 


Menu 


pause, show menu of priority 2 & 3 controls 
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Priority 1 Controls - fielding 

Semantic 

Aim 
Nearest 



-30- 
Description 

aim where to run or throw 
switch to fielder nearest to the ball 



Conservative Throw make conservative throw 



10 



Aggressive Throw 

Burst 

Jump 

Dive 

Menu 



make aggressive throw 
invoke burst of speed 
jump to catch ball 
dive to catch ball 

pause, show menu of priority 2 & 3 controls 



Priority 2 Controls - fielding 

x (none) 

Genre 7: 2D side to side movement 



Priority 1 Controls 

15 Semantic 

Move 
Throw 
Carry 
Attack 
20 Special 
Select 
Menu 



Description 

left / right / jump or climb or swim up / down 
throw object 
carry object 
attack 

apply special move 
select special move 

pause, show menu of priority 2 & 3 controls 
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Priority 2 Controls 

Semantic 

View 



Device 



Description 

scroll view left / right / up / down 

usually maps to POV on devices that have one 

displays input device and controls 



Genre 8: 2D Object Control (CAD) 



Priority 1 Controls 

Semantic 

Move 

10 View 
Zoom 
Select 
Special 1 
Special 2 

15 Special 3 

Special 4 
Menu 

Priority 2 Controls 

Semantic 

20 Rotate Z 

Display 
Device 



Description 

move object or scroll view up / down / left / right 
select between move and scroll 
in / out 

do first special operation 

do second special operation 

do third special operation 

do fourth special operation 

pause, show menu of priority 2 & 3 controls 

Description 

rotate object or view clockwise / counterclockwise 
shows next on-screen display options, etc. 
displays input device and controls 
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Genre 9: Browser Control 

Priority 1 Controls 

Semantic 

Pointer 
Select 

Forward/Back 
Page Up/Down 
Search 
Refresh 
Stop 

Priority 2 Controls 

Semantic 

Home 

Favorites 

Next 

Previous 

History 

Print 
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Description 

Move on screen pointer 

Select current item 

Move between items already seen 

Move view up/down 

Use search tool 

Refresh 

Cease current update 
Description 

Go directly to "home" location 
Mark current site as favorite 
Select Next page 
Select Previous page 
Show/Hide History 
Print current page 
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CQM: BINARY COMPATIBILITY 

Fig. 9 is a block diagram of a Microsoft Component Object Model software 
component that can be used to implement the present invention. The COM specification 

5 defines binary standards for objects and their interfaces, which facilitate the integration of 
software components into applications. COM specifies a platform-standard binary mapping 
for interfaces, but does not specify implementations for interfaces. In other words, an 
interface is defined, but the implementation of the interface is left up to the developer. The 
binary format for a COM interface is similar to the common format of a C++ virtual function 

10 table. Referring to Fig. 9, in accordance with COM, the COM object 900 is represented in the 
computer system 20 (Fig. 1) by an instance data structure 902, a virtual function table 904, 
and member methods (also called member functions) 906-908. The instance data structure 
902 contains a pointer 910 to the virtual function table 904 and data 912 (also referred to as 
data members, or properties of the object). A pointer is a data value that holds the address of 

15 an item in memory. The virtual function table 904 contains entries 916-918 for the member 
methods 906-908. Each of the entries 916-918 contains a reference to the code 906-908 that 
implements the corresponding member methods. A reference to an interface is stored as a 
pointer to the pointer 910. 

While extremely simple, the binary mapping provides complete binary compatibility 

20 between COM components written in any language with any development tool. Any 

language that can call a function through a pointer can use COM components. Any language 
that can export a function pointer can create COM components. Language-neutral binary 
compatibility is an important feature of COM. 

25 COM: STRONGLY TYPED INTERFACES AND INTERFACE DESCRIPTOR 
LANGUAGE 

The pointer 910, the virtual function table 904, and the member methods 906-908 
implement an interface of the COM object 900. By convention, the interfaces of a COM 
30 object are illustrated graphically as a plug-in jack as shown in object 1 1 00 in Fig. 1 1 . Also, 
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interfaces conventionally are given names beginning with a capital "I." In accordance with 
COM, the COM object 900 can include multiple interfaces, which are implemented with one 
or more virtual function tables. The member function of an interface is denoted as 
"IlnterfaceName: :MethodName." 
5 All first-class communication in COM takes place through well-defined, binary- 

standard interfaces, which are strongly typed references to a collection of semantically related 
functions. 

Programmatically, interfaces are described either with an Interface Definition 
Language (IDL) or with a package of compiled metadata structures called a type library. 

10 Whether expressed in IDL or a type library, the interface definition enumerates in detail the 
number and type of all arguments passed through interface functions. Each interface function 
can have any number of parameters. To clarify semantic features of the interface, IDL 
attributes can be attached to each interface, member function, or parameter. In IDL syntax, 
attributes are enclosed in square brackets ([]). Attributes specify features such as the data- 

1 5 flow direction of function arguments, the size of dynamic arrays, and the scope of pointers. 
Syntactically, IDL is very similar to C++. Moreover, the interface definition has a purpose 
similar to that of a function prototype in C++; it provides a description for invocation, but not 
an implementation. An IDL compiler maps the interface definitions into a standard format 
for languages such as C++, Java, or Visual Basic. For example, the Microsoft IDL compiler, 

20 MIDL, can map interfaces into C++ or export compiled IDL metadata to a type library. (For a 
detailed discussion of COM and OLE, see Kraig Brockschmidt, Inside OLE, Second Edition, 
Microsoft Press, Redmond, Washington (1995)). 

COM: GLOBALLY UNIQUE IDENTIFIERS 

25 In COM, classes of COM objects are uniquely associated with class identifiers 

("CLSIDs"), and registered by their CLSID in the registry. The registry entry for a COM 
object class associates the CLSID of the class with information identifying an executable file 
that provides the class (e.g., a DLL file having a class factory to produce an instance of the 
class). Class identifiers are 128-bit globally unique identifiers ("GUIDs") that the 
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programmer creates with a COM service named "CoCreateGUID" (or any of several other 
APIs and utilities that are used to create universally unique identifiers) and assigns to the 
respective classes. The interfaces of a component are also immutably associated with 
interface identifiers ("IIDs"), which are also 128-bit GUIDs. If an interface changes, it 
5 receives a new ED. 

COM: IMPLEMENTATION 

The virtual function table 904 and member methods 906-908 of the COM object 900 
are provided by an object server program 920 (hereafter "object server DLL") which is stored 
10 in the computer 20 (Fig. 1) as a dynamic link library file (denoted with a ".dll" file name 

extension). In accordance with COM, the object server DLL 920 includes code for the virtual 
function table 904 and member methods 906-908 of the classes that it supports, and also 
includes a class factory 922 that generates the instance data structure 902 for an object of the 
class. 

1 5 Other objects and programs (referred to as a "client" of the COM object 900) access 

the functionality of the COM object by invoking the member methods through the COM 
object's interfaces. First, however, the COM object must be instantiated (i.e., by causing the 
class factory to create the instance data structure 902 of the object); and the client must obtain 
an interface pointer to the COM object. 

20 Before the COM object 900 can be instantiated, the object is first installed on the 

computer 20. Typically, installation involves installing a group of related objects called a 
package. The COM object 900 is installed by storing the object server DLL file(s) 920 that 
provides the object in data storage accessible by the computer 20 (typically the hard drive 27), 
and registering COM attributes (e.g., class identifier, path and name of the object server DLL 

25 file 920, etc.) of the COM object in the system registry. The system registry is a per-machine 
component configuration database. 
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COM: COMPONENT INSTANTIATION 

A client requests instantiation of the COM object locally or on a remote computer 
using system-provided services and a set of standard, system-defined component interfaces 
based on class and interface identifiers assigned to the COM Object's class and interfaces. 
5 More specifically, the services are available to client programs as application programming 
interface (API) functions provided in the COM library, which is a component of the 
Microsoft Windows NT operating system in a file named "OLE32.DLL." The DCOM 
library, also a component of the Microsoft Windows NT operating system in "OLE32.DLL " 
provides services to instantiate COM objects remotely and to transparently support 

1 0 communication among COM obj ects on different computers. 

In particular, the COM library provides "activation mechanism" API functions, such 
as "CoCreatelnstanceO," that the client program can call to request local or remote creation of 
a component using its assigned CLSID and an IID of a desired interface. In response to a 
request, the "CoCreatelnstanceO" API looks up the registry entry of the requested CLSID in 

15 the registry to identify the executable file for the class. The "CoCreatelnstanceO" API 
function then loads the class' executable file either in the client program's process, or into a 
server process which can be either local or remote (i.e., on the same computer or on a remote 
computer in a distributed computer network) depending on the attributes registered for the 
COM object 900 in the system registry. The "CoCreatelnstanceO" API uses the class factory 

20 in the executable file to create an instance of the COM object 900. Finally, the 

"CoCreatelnstanceO" API function returns a pointer of the requested interface to the client 
program. 

COM: IN-PROCESS, CROSS-PROCESS, AND CROSS-MACHINE 
25 COMMUNICATION 

Binary compatibility gives COM components true location transparency. A client can 
communicate with a COM component in the same process, in a different process, or on an 
entirely different machine. Stated more succinctly, COM supports in-process, cross-process, 
30 or cross-machine communication. The location of the COM component is completely 
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transparent to the client because in each case the client still invokes the component by calling 
indirectly through an interface's virtual function table. Location transparency is supported by 
two facilities: MIDL generation of interface proxies and stubs, and the system registry. 

5 OVERVIEW OF MAPPER API 

Directlnput is the DirectX API for communicating with human interface devices, such 
as mice, keyboards, game controllers, and force feedback devices. The Directlnput Mapper 
("the Mapper") is designed to provide a common interface between devices and most game 
genres. The intent is to simplify the interface from devices to games and reduce the need for 
10 custom game drivers, custom device "profilers," and custom configuration user interfaces in 
games. 

Fig. 10 is a diagram showing concurrently executing applications 1000, 1002, and 
1 004 in the computer system 20. The Mapper API 1006 is a set of routines that the 
application programs use to request and carry out lower-level services performed by the 

15 operating system 1008 running on the computer system 20. For example, the applications 
invoke methods in the Mapper API to obtain information about input devices connected to the 
computer system 20 and to configure the system for interactions between the input device 
and the applications. The Mapper API may use default action-to-control mapping files and 
device images provided by Independent Hardware Vendors (IHV). The Mapper is currently 

20 implemented in DirectX 8.0, which is available from Microsoft Corporation®. 

Fig. 1 1 shows that DirectX includes interfaces and methods associated with those 
interfaces for linking controls on the input devices with actions that the applications perform. 
Two interfaces are shown: IDirectInput8 and EDirectInputDevice8. IDirectInput8 includes 
two methods called EnumDevicesBySemantics and ConfigureDevices. As described more 

25 fully below, EnumDevicesBySemantics determines the input devices connected to the 

computer system 20 that most closely match the actions of the application. Based on results, 
EnumDevicesBySemantics provides a ranking of the input devices to the application. 
ConfigureDevices invokes a user interface that allows the user to customize mapping of input 
device controls to actions of the application. 
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IDirectInputDevice8 has three methods called BuildActionMap, SetActionMap, and 
Getlmagelnfo. BuildActionMap is used to create an association between game actions and 
device controls. SetActionMap sets the action-to-control map in accordance with the 
association created in BuildActionMap. Getlmagelnfo allows applications to customize the 
5 user interface displayed for configuring the devices. 

DETAILS OF MAPPER API 

Mapper Extensions 

Directlnput for DirectX 8.0 includes two new interfaces: IDirectInput8 and 

10 BDirectInputDevice8. These interfaces do not extend their predecessors, but extends their 
features to include methods that support the action-to-control mapping features that make up 
the Directlnput Semantic Mapper. The Mapper simplifies application development by 
presenting a unified mechanism to tie game actions to device controls. It allows games to 
take full advantage of devices that come to market, even after the game has shipped. 

1 5 The game-action-to-device-control mappings made possible by the Mapper are not 

immutable; that is, applications can override the suggested mappings with their own. 
Applications that do not use the Mapper to enable users to reconfigure devices (games with 
finely tuned keyboard mappings, for instance) can still benefit from a simplified input loop 
made possible by generalizing device input from in-game actions. Additionally, these 

20 applications can use the Mapper's companion Device Configuration user interface in "view 
mode" to display the current configuration without necessarily allowing changes to be made. 

An action expresses what application behavior should result from the user's operation 
of a control. A genre defines a set of actions that are common to most games of that general 
type. The Mapper takes into account user preferences and information from the device 

25 manufacturer to determine the association between an action and a given device control. The 
Mapper provides a consistent mechanism for games to configure their input. 
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Market Justification 

Entertainment software in today's market encompasses dozens, if not hundreds, of 

clearly distinguishable genres — first-person shooters, vehicle racing games, flying and 
combat simulations, sports titles, adventure games, and RPGs are just a few. There are any 

5 number of possible "hybrid" games that mix genres for various parts of gameplay. Actions 
that users perform in a given game genre are often ubiquitous to that genre. Take a car racing 
game, for instance. Almost all racing games include common actions: steer, accelerate, brake, 
upshift, downshift, etc. The same can be said of most all games in most all genres. 

Currently, software developers translate raw device data into meaningful game 

10 actions, which often represents a significant portion of a game's input loop, or uses a custom 
input front-end. The Directlnput Mapper serves to decrease the ISV ! s development overhead 
by simplifying the input loop and offloading input-data-to-game-action translation onto 
Directlnput. The Mapper also includes support in the OS for a default device configuration 
UI, eliminating the need for ad hoc code in each title. API elements exist for ISVs to develop 

15 their own UI, if the default UI does not fit within the context of the title. When the Mapper is 
employed by ISVs and IHVs, title development will be easier and, most importantly, the user 
experience will be more consistent and reliable. 

Example: Race Car Simulator 

20 The following example illustrates how a car racing game may be used by the Mapper 

to configure input. The enumeration provided by the application developer, called 
eGameActions, supplies codes that Directlnput uses to communicate the state of controls. The 
values defined by eGameActions abstract the device controls, so the same input loop can be 
used for all configured input devices. The game's input loop need only implement a switch 
25 that modifies the behavior of the game based on the actions it receives, without concern about 
the device that provides the control for the action. More capable devices that come to market 
after the game shipped can enable additional game actions merely by being capable of 
accommodating more actions, without any modification. 
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An application may enumerate all the actions that it plans to expose to users. Actions 
that may use axis and hat-switch controls should also have button or key equivalents, which 
allows users to configure those actions on less capable devices. The following is a sample 
enumeration that might be defined by a car racing title. 
5 enum eGameActions{ 



10 



// 


"eA " designates 


; an axis, "eB_ 


" is for 


a button 


eA_ 


_STEER , 


// 


Steering 








eB_ 


_STEER__LEFT , 


// 


Use button to 


steer to 


the 


let t 


eB_ 


_STEER__RIGHT, 


// 


Use button to 


steer to 


the 


right 


eA_ 


_ACCELERATE , 


// 


Accelerate 








eB_ 


^ACCELERATE , 


// 


Use button to 


accelerate 




eB_ 


_DECELERATE , 


// 


Use button to 


decelerate 




eA_ 


_BRAKE , 


// 


Brake 








eB_ 


J3RAKE , 


// 


Brake button 








eB_ 


_UPSHIFT, 


// 


Shift to higher gear 






eB_ 


_DOWNSHIFT, 


// 


Shift to lower gear 






eB_ 


_CYCLEVIEW, 


// 


Cycle to next 


view 






eB_ 


_CONFIGCAR, 


// 


Configure vehicle 






eB_ 


_COURSEVIEW, 


// 


Toggle course 


view 






eB_ 


JDRIVERVIEW, 


// 


View from Drivers seat 






eA_ 


_VOLUME, 


// 


Music volume 








eB_ 


JVIUTE, 


// 


Mute music 








eB 


BRAKEBIAS, 


// 


Brake Bias 









eMAX_MY_ACT IONS 

25 }; „ _„ „„. 

Applications bind the actions they support to the semantics in a given genre by using 
an array of DIACTION structures. Each structure in the array defines an application-defined 
action value, the pre-defined genre action semantic it applies to, and data that can be used to 
present a friendly name that describes the action. The DIACTION array serves two purposes: 

30 it is used to request a list (via a callback function) of connected devices known to DirectLaput 
that match the desired actions closely, and to retrieve and set the mappings within a chosen 
device. The array of DIACTION structures is wrapped into a header structure, 
DIACTIONFORMAT, for all transactions between the application and Directhiput 
(DIACTIONFORMAT is discussed below). 

35 hi the following example, rgActions is an application-defined array of DIACTION 

structures that binds game action codes to devices and controls on those devices. 
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PI ACTION rgActions [] = 

{ 

// Genre Defined controls 

/************* ****************** 

Game Code Action Code 

************** ****************** 

//Genre defined axes 

{eA_STEER, DIAXIS_DRIVINGR_STEER, 

{ eA_ACCELERATE , DIAXIS_DRIVINGR__ACCELERATE , 0 , 



{ e A_BRAKE , 



D I AX I S_DRI VINGR__BRAKE , 



//Genre defined buttons 

{ eB_UPSHIFT , DIBUTTON_DRIVINGR_SHIFTUP , 0 , 

{ eB_DOWNSHI FT , DIBUTTON_DRIVINGR__SHIFTDOWN / 0 , 

{ eB_CYCLEVIEW , DIBUTTON_DRIVINGR_VIEW , 
View"), }, 

{ eB_CONFIGCAR , DIBUTTON_DRIVINGR_MENU, 



**************** 

Label For Action 
****************/ 

0, TEXT ("Steer") , 

TEXT ("Accelerate" ) , 
0, TEXT ("Brake") , 

TEXT ("Upshift") , 
TEXT ( "Downshift" ) , 
0, TEXT ("Change 
0 , TEXT ( "Configure" ) , 



// Additional axes not defined as part of the genre 
// Listed in order of importance 

{ eA_VOLUME , DIAXIS_ANY, 0, TEXT ( " CD Volume " ) , 



{eB_MUTE / 



DIBUTTON_AKTY, 



0, TEXT ("Mute Volume"), 



// ...More game specific actions 

// Additional actions not defined in the car controller genre 
// Listed in order of importance. 

{eBJDRIVERVIEW, DIKEYBOARD_l , 0, 

{eB_COURSEVIEW, DIKEYBOARD_C , 0, 

{ eB_BRAKEBIAS , DIKEYBOARD_B, 0, 
// ...More game specific actions. 



TEXT ("Driver View"), }, 
TEXT ("Course View"), } 
TEXT ("Brake Bias"), } 



// Equivalent mapping for keyboard 

{ eB_STEER_L , DIKEYBOARD_LEFT, 0, TEXT ( " Steer Left ") , 

{eB_STEER_R, D I KE YBOARD_R I GHT , 0 , TEXT ( "Steer Right" ) 

{eB_ACCEL_MORE, D I KE YBOARD__UP , 0, TEXT ( "Accelerate ») , 

{eB_ACCEL_LESS, D I KE YBOARD_DOWN , 0, TEXT ( "Decelerate ") , 

{ eB__BRAKE , D I KE YB OARD__END , 0, TEXT ( "Brake ") , 

// ...Additional mapping for keyboard 
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// Equivalent mouse mapping 

(eB_UPSHIFTl, DIMOUSE_BUTTON0 , 0, TEXT ( "Upshift " ) , 
{ eB__DOWNSHIFTl , DIM0USE_BUTT0N1 , 0, TEXT ( "Downshift ") , 
{eB_CYCLEVIEW, DIMOUSE_WHEEL , 0, TEXT ( "Cycle View" ) , 

// ...Additional mapping for mouse _ 

The rgActions array specifies a template for associations between game actions and 
device controls. Device controls can be specified either on gaming devices or keyboard / 
mouse. Actions on gaming devices are mapped with the help of information from user 
preferences and device manufacturer provided mappings. For standard devices (keyboard, 
mouse) or specific devices whose layout is well known the controls maybe specified by 
direct reference. If the application permits, a user can re-map keyboard/mouse controls to 
some other device(s). 

Genre semantics provide a way to map actions to controls on custom gaming devices, 
even if released after the game is developed. Note that for standard devices such as the 
keyboard or mouse, physical mappings are provided. This allows developers to closely 
control the mapping of actions to known standard devices. 

An application initially passes its rgActions array (or its equivalent array of DIACTION 
structures) to Directlnput by way of the IDirectInput8::EnumDevicesBySemantics method. 

As stated previously, the DIACTIONFORMAT structure serves as the carrier for an 
application's DIACTION array (in this example, it is rgActions). With the action array 
defined, the application can build an appropriate DIACTIONFORMAT structure to act as the 
carrier for its rgActions array. This structure is a simple wrapper for the application's array of 
DIACTION structures. The application can choose to specify a default data axis range as a 
member of the DIACTIONFORMAT. This default range will apply to all configured devices. 
For example, a game may prefer all input axes to report data in the range of {-100, +100}, 
with 0x0 as the nominal center. The range for individual actions can still be configured 
through the SetProperty method. The following example initializes a DIACTIONFORMAT 
structure for the rgActions array. 

DIACTIONFORMAT g_diActionDf = 

{ . .. - - - 
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sizeof "(DIACTIONFORMAT) , 
sizeof (DIACTION) , 

II Size of buffer for immediate device data. 

eMAX_MY_ACT IONS * sizeof { ( (LPDIDEVICEOBJECTDATA) 0) ->dwData ), 
5 eMAX_MY_ACTIONS , 

rgActions , 
GUID_Application / 
DI VIRTUAL_CARCONTROLLER , 
16, 

10 L_AXIS_MIN, 
L_AXIS_MAX, 
NULL, 
0, 
0, 

15 TEXT (" Racing Controls") 

The dwDataSize member represents the size, in bytes, of the device data buffer that 
should be returned for by the device for immediate data retrieval. (However, most 
20 applications will usually use buffered device data.) Applications should set this member to 
the value in dwNumActions multiplied by four. 

Given a prepared DIACTIONFORMAT structure, the application can enumerate the 
connected devices that match the actions it needs by calling 
IDirectInput8::EnumDevicesBySemantics, as in the following example. 

25 

Initializelnput ( ) 

{ 

HRRESULT hr; 

IDirectInput8* pDI = NULL; 

30 

// Create Direct Input interface 
hr = DirectlnputCreateEx ( 

g_hinst, DIRECTINPUT_VERSION, 

&IID_DirectInput8, (void**)pDi, NULL) ; 

35 

if (FAILED (hr) ) { 
goto panic; 

} 



40 



// Enumerate devices for my actions, 
hr =pDI->EnumDevicesBySemantics ( 
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TEXT("1UP") , 
&g_diActionDf , 
f nDIEnumDe vices , 
NULL, 
0x0) ; 

if (FAILED (hr) ) 

{ //No devices were found, 
goto panic; 



// UserName, NULL=>CurrentUser 
// Action data format 
// Device Enumeration function 
// User variable 
// Enumeration flags 



10 } 

panic : 

if (pDI) 

pDI->Release {) ; 

15 } 



When the application calls IDirectInput8::EnuinDevicesBySemantics, Directlnput 
examines all connected devices and invokes an application-defined callback function to 
enumerate the connected devices that match the desired game actions most closely. In the 
20 callback function, the game can build a list of available devices and allow the user to 
configure each device. The following represents a typical callback function. 



BOOL f nDIEnumDevices ( 

LPCDIDEVICE INSTANCE IpDIdi , 
25 LPDIRECTINPUTDEVICE8 TpDiDev, 

DWORD dwFlags, 

DWORD dwDevicesRemaining, // The number of devices, after this one, 
left to be enumerated. 
PVOID pContext) 

30 { 

LPBOOL lpB = (BOOL*) pContext ; 

BOOL blsSystemDev = (lpDIdi->dwDevType & 
(DIDEVTYPE_MOUSE | D IDEVTYPEJKE YBOARD ) ) ; 
35 BOOL bRecent - (dwFlags & DIEBS_RECENTDEVICE) ; 

BOOL bNew = (dwFlags & DIEBS_NEWDEVICE) ; 

//If there are no recent devices, this could be the very first time 
// the application is being run, and it may want to prompt the user 
40 //to choose a device. Also, apps may want to cue the user to 

// select a device if a new device is found, 
if ( !Recent | | bNew ) 
*lpB = TRUE; 
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// If the device has had an action map applied recently, assume that 
// the user is actively using the device. Also prepare all system 
devices, 

5 // such as the mouse or keyboard. 

if( blsSystemDev || TRUE == *lpB) 

{ 

// Obtain the action to device control mapping, 
hr = lpDiDev->BuildActionMap (&g_diActionDf , lptszUserName, 
10 DIDBAMJDEFAULT) ; 

// Once actions have been mapped to the device controls the 

// application can review the mapping and may want to modify the 

map . 

15 // . 

// . 
// . 

hr = lpDiDev->SetActionMap (&g_diActionDf , lptszUserName, 
20 D IDS AM_DE FAULT ) ; 

//If you decide to keep the device, you need to AddRef () 
// the interface. 
lpDiDev->AddRef () ; 



25 



// Set the cooperative level for device access. 
lpDiDev->SetCooperativeLevel (...) ; 



// Save the interface pointer 
30 g_llpDiDevices [g__nDevices++] = IpDiDev; 

} 

// Look for other devices 

return DIENUM_CONTINUE; 

35 Note that mappings for the enumerated devices may not exactly match the action array 

provided by the application; applications can query an enumerated device for its mappings by 
way of IDirectInputDevice8::BuildActionMap ? change them, then commit them to the device 
by calling K)irectInputDevice8::SetActionMap. If the settings for the device have changed 
(verified through a CRC check), Directlnput automatically persists them to disk. 

40 With the Mapper properly prepared, the input loop for the game is considerably 

simplified. The application need not try to parse incoming device data; it gets its own action 
values. (Applications can even use function pointers as action values.) The following example 
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shows a for loop that runs through all configured devices, polls them, obtains data from each, 
and takes action in a switch statement based on the action. 

// For all configured input devices 

for(iDevice= 0x0; iDevice < g_nDevices; iDevice++) 

5 { 

DIDEVICEOBJECTDATA didod; 

HRESULT hr; 

DWORD dwObj Count = 1; 

10 // Some devices are polled, others are interrupt -driven . The Poll 

method 

// quickly returns S_FALSE on interrupt -driven devices. 
g__lpDiDevices [iDevice] ->Poll () ; 

15 // Get device data 

hr = g IpDiDevices [iDevice] ->GetDeviceData ( sizeof (didod) , 

&didod, 

&dwOb j Count , 0 ) ; 

20 if (FAILED (hr) ) goto Panic; 

// Switch based on the uAppData field in the DIDEVICEDATA field 
//No dependency on input device 
switch (didod.uAppData) 

25 { 

case eA_STEER: 

SteerCar (dwData) ; 

break; 
case eA_BRAKE : 
30 Decelerate (dwData) ; 

break; 



35 



40 



default : 
break; 

} 

} 



Low-level UI API 

Directlnput also supports a low-level API to retrieve the same data used to display the 
default user interface. This data provides the application with access to the device images, 
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overlays, callout lines and callout text rectangles. The IDirectInputDevice8 interface provides 
a new method for this purpose— IDirectInputDevice8::GetImageInfo —and two related 
structures. The low-level API does not impose a UI paradigm on the application developer; it 
simply provides the lowest-level data access possible, from which a custom UI can be 
5 developed. 

The IDirectInputDevice8::GetImageInfo method returns general information that might 
be needed to display the user interface (in the form of a DIDEVICEIMAGEINFOHEADER 
structure): 

(a) Images. The total number of images, including the device selection view, alternate 
10 mini-view images, the configuration views, and all overlays. 

(b) Views. The total number of device configuration images for this device. 

(c) Buttons. The count of buttons for the device. 

(d) Axes. The count of axes for the device. 

1 5 The DIDEVICEIMAGEINFOHEADER contains a pointer to an array of 

DIDEVICEIMAGErNFO structures, which provide data needed to display images, callouts, 
and labels. 

(a) Image path. The fully qualified path to the device image file. 

(b) Image file format. Describes the file format of the device image. For DirectX 8.0, 
20 the only publicly supported format is PNG, 384x320, with alpha. Dimensions are not 

arbitrary, they were chosen because to be easily split into square, power-of-2 textures, 
to accommodate the widest variety of display cards. For example, 384x320 = 
(256+128)x(256+64), which can be done with one 256x256 texture, two 128x128 
textures, and six 64x64 textures for a total of 9 textures when there is a square power- 
25 of-2 surface limitation. Parts without this limitation require fewer sections. 

(c) Image type. Describes the purpose of the image (device configuration, selection, 
etc.) 

The following information is also included in the structure, but is only valid for 
device controls (usually overlays). 
30 (d) View ID. The zero-based ID of the base image over which an overlay is to be 
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displayed. 

(e) Overlay rectangle. The rectangle, relative to the top-left corner of the base image, 
where the overlay should appear. 

(f) Object ID. The object ID (for instance, DIJOFSJQ of the control on the device to 
5 which this overlay applies. 

(g) Callout line. The one- to four-segment line for the callout 

(f) Callout rectangle. The rectangle in which the action string should be displayed, 
(i) Text alignment. Left-justified, centered, or right justified. Required to properly 
display text within callout rectangles that could be above, below, left, or right of the 
1 0 endpoint of the callout line. 

An application can call the IDirectInputDevice8::GetImageInfo method once for each 
device, passing 0 in the dwBufferSize member, which causes the method to simply calculate 
the required size and return that value in the dwBufferUsed member. This value is used by the 
1 5 application developer to determine how many DIDEVICEIMAGE structures to allocate in an 
array, which is contained by the DIDEVICEIMAGEINFOHEADER structure. Other 
information in the structure is provided mainly for convenience. After the array is allocated, 
the application can call IDirectInputDevice8::GetImageInfo. 

The following example shows how this might look in code: 

20 " D I DEV I CE II^GE INFOHE ADER dilmginf oHdr ; 
LPD I DEVICE I MAGE INFO lprgdilmgData; 

ZeroMemory{ &dilmglnf oHdr , sizeof (DIDEVICEIMAGEINFOHEADER) ); 
dilmglnfoHdr.dwSize = sizeof (DIDEVICEIMAGEHEADER) ; 

25 

// Retrieve the required buffer size. 
lpDIDev->GetImageInf o ( kdilmglnf oHdr ); 

// Allocate the buffer. 
30 lprgdilmgData = ( LPD IDE VI CE IMAGE INFO ) malloc ( (size_t) 

dilmglnfoHdr. dwBufferUsed ); 

dilDHeader.lprglmageDataArray = lprgdilmgData; 



35 



// Get the display info. 

lpDIDev->GetImageInfoi ( &dilmglnf oHdr ) ; 
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Exactly how the application uses the information to create a user interface is not 
within the scope of this specification. The developer is free to produce their own UI paradigm 
(tabbed, wizard-like, 3D, etc.). 

5 SEMANTIC MAPPER API 

Interfaces 

EnumDevicesBySemantics 

Fig. 13 is a flowchart of a method for implementing 

IDirectInput8::EnumDevicesBySemantics. This method examines the genre specified by the 

10 application and enumerates devices that most closely match. 

In process box 1302, the API receives actions from the application. For example, the 

actions may be passed in an action array, such as contained in the DIACTIONFORMAT 

structure (described further below). Other techniques for passing the actions to the API may 

also be used. 

15 In process box 1304, the API examines input devices attached to the computer. For 

example, the API may determine the keyboard and a Side Winder Game Pad Pro are attached 

to the computer system 20. 

In process box 1306, the API provides the input devices to the application based on 

how suitable the input devices are to the application. Thus the API analyzes how many of the 
20 semantics of the C-S correlations 221 (Fig. 3) match the semantics of the A-S correlations 

231 (Fig. 4). The input devices can be provided in a list, table, array, etc. Alternatively, the 

API can invoke an application-defined callback function that returns the ranking through 

repeated calls to the application. 

The application uses the information from the API to select an input device. The 
25 information is only suggestive. The application can ignore the suggested information from 

the API and choose the input device that the application believes is optimal. 

A specific implementation of EnumDevicesBySemantics is shown below. In 

examining available devices, Directlnput uses information about current user preferences and 

hardware manufacturer provided action maps. 
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HRESULT IDirectInput8 : : EnumDevicesBy Semantics ( 
LPTSTR pt szUserName , 

LPDIACTTONFORMAT pdiAct ionFormat , 

LPDIENUMDEVICESBYSEMANTICSCB pcallback, 
5 LPVOID pAppData, 

DWORD dwFlags) ; _ _ _ t __ _ 

ptszUserName is a string identifying the user name. Passing NULL is valid, indicating 
the user currently logged-in to the system. The user name is taken into account when 
enumerating devices. A device with user mappings is preferable to a device without any user 
10 mappings. Devices in use by other users will not be enumerated for this user (by default, see 
flags). 

pdiActionFormat is a pointer to a DIACTIONFORMAT structure that contains the 
action map array for which suitable devices will be enumerated. 
pcallback is a pointer to a callback function (of prototype 
1 5 LPDIENUMDEVICESBYSEMANTICSCB) to be called once for each device enumerated. 
pAppData is an Application-defined 32-bit value to be passed to the enumeration 

callback each time it is called. 

dwFlags includes flags that specify the scope of the enumeration. This parameter can 

be one or more of the following values: 

20 

DIEDBSFLAVAILABLEDEVICES 

Only unowned installed devices are enumerated. 

DIEDBSFL_ THISUSER 

All installed devices for the user identified by ptszUserName are enumerated. 

25 DIEDBSFL_A TTA CHEDONL Y 

Only attached and installed devices. If the DIEDBSFLJTHISUSER flag is also 
present, the method will enumerate all devices owned by the user name at 
ptszUserName, and all unowned attached devices. 

30 DIEDBSFL_FORCEFEEDBACK 

Only devices that support force feedback. 

DIEDBSFLJMULTIMICEKEYBOARDS 

Only secondary (non-system) keyboard and mouse devices. 

DIEDBSFLNONGAMINGDEVICES 

3 5 Only HID-compliant devices whose primary purpose is not as a gaming device. 

Devices such as USB speakers, multimedia buttons on some keyboards, and such 
are within this category. 
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EnumDevicesBySemantics may return the following error codes, though other 
standard COM or Directlnput error codes may be returned: 
DI_OK 

5 DIERRJNVALEDP ARAMS 

DIERRNOTINITIALIZED 

ConfigureDevices 

Fig. 14 is a flowchart of a method for configuring the UL In process box 1402, 

10 IDirectInput8 "ConfigureDevices determines the input devices that are attached to the system, 

which is well understood in the art. In process box 1404, ConfigureDevices obtains system 

information about the input devices stored on the computer system. For example, IHVs may 

supply information in the form of .ini files that describe buttons, levers, etc. on the input 

device. Additionally, information about how to display the UI is obtained, such as where to 

15 display text on the UI, where to draw lines extending from the text to a control on the input 

device, etc. In process box 1406, ConfigureDevices retrieves custom settings that the user 

has set for this device. Such custom settings are also stored on the computer system 20. In 

process box 1408, the UI is displayed to the user using the information obtained from the 

system and the custom settings. ConfigureDevices can either render the UI directly by 

20 placing the rendering information in a screen buffer or can pass the rendering information 

back to the application. 

A specific implementation of ConfigureDevices is now described. 

IDirectInput8:: ConfigureDevices invokes the default Directlnput configuration (Mapper) 

user-interface. Calls to this method are synchronous. 

25 _ _ i _ _ 

HRESULT IDirectInput8 : : ConfigureDevices ( 

LPD ICONF IGUREDEVI CES CALLBACK IpdiCallback, 

LPD I CONF I GUREDE VI CE S P ARAMS IpdiCDParams , 

DWORD dwFlags, 
30 LPVOID pvRefData) ; 

IpdiCallback 

Pointer to the ConfigureDevicesCallback function for the application. This can be 
NULL to cause Directlnput to display the UI (windowed-mode applications only). If a 
callback function is specified, the UI is not displayed by Directlnput. Rather, the UI is placed 
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into the target surface provided within the DICONFIGUREDEVICESP ARAMS structure, 

and the callback function is invoked. 

IpdiCDParams 

Address of a DICONFIGUREDEVICESP ARAMS structure that contains information 
5 about users and genres for the game, as well as data controlling in part how the UI is 
displayed. 
dwFlags 

Flags specifying the mode in which the control panel should be invoked. This 
parameter can be one of the following values. 

10 DICD__DEFAULT 

Open the control panel in view mode, the default setting. While in view mode, the control 
panel acts simply to display the current device configuration. 

DICD^EDIT 

15 Open the control panel in edit mode. This mode allows the user to change action-to- 
control mappings through the control panel. After the call returns, the application should 
assume current devices are no longer valid used, release all device interfaces and 
reinitialize them through enumeration (IDirectInput8::EnumDevicesBySemantics). 

20 pvRefData 

Application-defined value to be passed to the callback function. 

This method can return the following error codes, though other standard COM or 
Directlnput error codes may be returned: 

25 DI_OK 

DIERRJNVALIDPARAMS 
DIERROUTOFMEMORY 

Hardware vendors provide bitmaps and other display information for their device, 
30 Prior to invoking ConfigureDevices, application developers can modify the text labels 

associated with each action in the DIACTION structure to accurately reflect the context 
within the game. 

Users can set up the configuration for each connected device, the configuration 
information is stored on a per-game and per-user basis. The application GUID and user name 
35 are used to store unique configuration information, which can be retrieved by the 
IDirectlnputDeviceS: :BuildActionMap method. 
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After the method returns from edit mode, applications should assume that mappings 
have changed. They should subsequently destroy and re-create their input devices (getting the 
new mappings). 

IDirectInputDevice8 is another interface having three methods each discussed in turn 
5 below: BuildActionMap, SetActionMap, and Getlmagelnfa 

BuildActionMap 

Fig. 15 shows a flowchart of a method for implementing BuildActionMap. 
BuildActionMap creates the mapping of actions to controls for the selected input device. 

1 0 Information about user preferences and hardware manufacturer provided defaults is used to 
create the association between game actions and device controls. 

In process box 1502, the API receives the actions that the application needs to 
implement (e.g., steering, braking, etc.). In process box 1504, a check is performed for a file 
that identifies input devices previously used by the user and the associated settings the user 

1 5 had for that device. In decision box 1 506, if such a file exists, then the user's previous 

configurations are used for the action-to-control map (process box 1 508). If such a file is not 
found (or if the file does not include the desired configuration information), then alternate 
steps are needed to generate the action-to-control mapping. In decision box 1510, a check is 
made whether a default mapping exists. If decision box 1510 is answered in the affirmative, 

20 then in process box 1512, the default mappings are obtained. Such default mappings are 
stored in a file provided by the hardware vendor that indicates the different applications and 
action-to-control map for the applications. In process box 1514, the default mappings are 
used to create the action-to-control map. 

If default mappings do not exist, then initial defaults are generated using lightweight 

25 heuristics (process box 1518). Finally, in process box 1522, the generated defaults are used 
to create the action-to-control map. 

A specific implementation for BuildActionMap is as follows: 

IDirectInputDevice8 : : BuildActionMap ( 
30 LPDIACTIONFORMAT IpdiActionFormat , 

LPCSTR IptszUserName, 
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DWORD dwFlags) ; 

IpdiActionFormat 

Pointer to a DIACTIONFORMAT structure that will receive the control-to-action 
mapping for this device. 

5 IptszlIserName 

String specifying the user's name. The name is used to retrieve preferences on a per- 
user basis. Passing NULL is valid, indicating current user. 
dwFlags 

Mapping control flags. This parameter can be one of the following flags. 

10 DIDBAMJ)EFAULT 

Retrieve action-to-control mappings for this device, overwriting all mappings except 
application-specified mappings (DIAAPPMAPPED). 

DIDBAMJNITIALIZE 

15 Retrieve action-to-control mappings for this device, overwriting all mappings, including 
application-specified mappings (DIAAPPMAPPED). 

DIDBAMJIWDEFAULTS 

Retrieve action-to-control mappings for this device, overwriting all mappings, including 
20 application-specified mappings (DIAAPPMAPPED). This flag is similar to 

DIDB AM INITIALIZE, but automatically overrides user-mapped actions with the 
IHV/Directlnput defaults. 

DIDBAM_PRESERVE 

25 Retrieve action-to-control mapping, preserving any currently set mappings assigned for 
this device or any other configured device. 

This method can return the following error codes, though other standard COM or 
Directhiput error codes may be returned: 

30 DIJOK 

DISETTINGSNOTSA VED 

The action map was applied to the device, but the settings could not be persisted. 

DIERRINVALIDP ARAMS 

35 One of the mappings in the action-to-control map was not valid. The entry was marked 

DIAHERROR. The application can iterate through the action map to find and correct the 
error. 

If this method fails when using the DIDGAMDEFAULT flag, the retrieved action- 
40 to-control mappings should be assumed incomplete. The application should check for and 
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eliminate invalid values present in the dwHow members of the associated DIACTION 
structures, then call the method again. 

SetActionMap 

5 Fig. 16 illustrates IDirectInputDevice8::SetActionMap. SetActionMap sets the 

action-to-control map for this device/user combination, saving settings to disk if this is a new 
action-to-control map for the user. A distinction that should be recognized between the 
physical device codes received from an input device and generic semantic associated with that 
code. For example, a generic semantic could be "fire guns." However, if the user activates 

1 0 the user input device to fire guns, the API may receive a controller code 1002, which is an 
indication to fire guns. The application, on the other hand, expects "fire guns" to be 
application code "64379." BuildActionMap creates an association for the generic semantics. 
Once BuildActionMap creates the generic action mapping, SetActionMap completes the 
actual control-to-action mapping by ensuring that the controller codes are mapped to the 

1 5 associated application codes. Thus, the results of BuildActionMap are used to set the action- 
to-control map to bind the marriage of the device to the application. At this point, the device 
can communicate with the application. 

In decision box 1604, a check is made to determine whether the action-to-control 
mapping has previously been saved to disk in its current form. If it has, in process box 1606, 

20 the settings are automatically saved to disk. These settings may then be used in 

BuildActionMap when the same application is used again with the same input device. 

In process box 1608, using the action-to-control mapping, the API maps the controller 
codes for the device with the application codes. 

A specific implementation of SetActionMap is as follows: 

25 This method should be called while the device is unacquired. 

j IDirectInputDevice8 : : SetActionMap { 
' LPDIACTIONFORMAT lpdiActionFormat , 

LPCSTR lptszUserName, 
! DWORD dwFlags 
30 : ) ; 
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IpdiActionFormat 

Pointer the DIACTIONFORMAT structure containing the action-to-control mapping 
5 data to be set for this device. 
IptszUserName 

Name of the user for which the action map is to be set. NULL is valid for the user 
currently logged-into the system. 
dwFlags 

1 0 Application control flags. 

DIDSAMDEFA ULT 

Set the action-to-control map for this user. If the map differs from the currently set map, 
the new settings are saved to disk. 

1 5 DIDSAMFORCESA VE 

Device mappings should be saved even if the device in the default configuration UI 
should be set to no owner. Resetting user ownership does not remove the currently set 
action-to-control map. 

20 DIDSAMJfOUSER 

(Used only for default UI). Reset user ownership for this device in the default 
configuration UI. Resetting user ownership does not remove the currently set action-to- 
control map. 

25 This method can return the following error codes, though other standard COM or 

Directlnput error codes may be returned: 
DI_OK 

DISETTINGSNOTSA VED 

The settings have been successfully applied but could not be persisted; 

30 

DIERRJNVALIDPARAM 

Invalid parameter was passed. 

DIERR_ACQUIRED 

Settings cannot be saved while a device is acquired. 

35 

This method provides the mechanism to change action to control mapping from the 
device defaults. An application must use this method to map its in-game actions to device 
control semantics. 

The user name passed to this method binds a set of action-to-control mappings for a 
40 device to a specific user. Settings are automatically saved to disk when they differ with the 
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currently applied map, however device ownership is not persisted to disk. Applications that 
accept input from multiple users should be very careful when applying action maps to system 
devices (GUID_SysMouse, GUID_SysKeyboard), as the action maps for each user may 
conflict. 

5 

Getlmagelnfo 

Fig. 17 shows a flowchart of a method for Getlmagelnfo, which retrieves device 
image information for use in displaying a configuration UI for a single device. 

In process box 1702, the input device image information is retrieved. The retrieved 
1 0 information is provided by an IHV and includes recommended rendering information, such as 
how to draw lines and where text should be placed in the UI of the input device. In process 
box 1704, the API builds a data structure that describes the image information to the 
application so that the application can customize the UI. hi process box 1706, the API 
provides the data structure to the application. A specific implementation of Getlmagelnfo is 
15 as follows: 

HRESTJLT lDirectInputDevice8 : : Getlmagelnfo ( 

LPDIDEVICEIMAGEINFOHEADER lpdiDevImagelnf oHeader 

20 IpdiDevImagelnfoHeader 

Pointer to a DIDEVICEDVIAGEINFOHEADER structure that will receive image 

information that can be used to display custom configuration user interface. 

This method can return the following error codes, though other standard COM or 
25 Directlnput error codes may be returned: 
DIERRJNVALIDPARAMS 

The parameter IpdiDevImagelnfoHeader is invalid, or the contents of the structure it 
points to are invalid. 

30 DIERR_NOTINITIALIZED 
The object is not initialized. 
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If the dwBufferSize member of the DIDEVICEIMAGEINFOHEADER structure is set 
to zero, this method computes the minimum size, in bytes, of the buffer placing the value in 
the dwBufferUsed member. 

Not all devices will have image information. If no image is available for the device, 
5 the tszImagePath member of the DIDEVICEIMAGEINFO structure will be set to NULL. If 
so, the application is responsible for enumerating controls on the device and displaying a 
default listing of actions to device controls (similar to the method used by most applications 
before DirectX 8.0). 

10 STRUCTURES 

The DIACTION structure forms the basis for the Mapper. Its members carry data to 
describe a mapping of one game action to one device semantic. The structure is used by 
IDirectInput8::EnumDevicesBySemantics to examine the input requirements and enumerate 
suitable devices, by IDirectInputDevice8::BuildActionMap to resolve virtual device controls 
1 5 to physical device controls, and by IDirectInputDevice8: :SetActionMap to set the action map 
for a device. 



typedef struct JD I ACTION { 

UINT_PTR uAppData ; 

20 DWORD dwS eman t i c ; 

DWORD dwFlags ; 

union { 

LPCTSZ IptszActionName; 
OPTIONAL UINT uResIdString; 
25 } DUMMYUNIONNAMEN ( 1 ) ; 

OPTIONAL GUID guidlnstance ; 
OPTIONAL DWORD dwObjID; 
OUT DWORD dwHOW; 
} DIACTION, *LPDIACTION; _ ^ _ 

30 

uAppData 

Application-defined value to be returned to the application by 
E)irectInputDevice8:GetDeviceData when the state of the control associated with the action 
changes. This value is returned in the uAppData member of the DIDEVICEOBJECTDATA 
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structure. This is typically an identifier for the application-specific action associated with the 

device object, but can be a function pointer. 

dwSemantic 

For gaming devices, one of the predefined semantics for this application genre. For a 
5 mouse or keyboard (DIPHYSICAL__MOUSE or DIPHYSICAL_KEYBOARD), a specific 
control object on the device. 
dwFlags 

Flags used to request specific attributes or processing. Can be 0 or one or more of the 
following values: 

10 DIAFORCEFEEDBA CK 

The action must be an actuator or trigger. 
DIA__APPMAPPED 
The dwObjLD member is valid. 
DIA__APPNOMAP 
1 5 This action is not to be mapped. 
DIA__NORANGE 

The default range is not to be set for this action. This flag can be set only for absolute 
axis actions. 
IptszActionName 

20 Friendly name associated with the action. This string will be displayed by the Input 

Configuration control panel to describe the action assigned to a device control. If a resource 
ID is specified in the wResEDString member, this member is ignored. 
uResIdString 

Resource ID for the string for this action. The module instance for this resource is 
25 specified in the DIACTIONFORMAT structure that contains this structure. This member is 
ignored unless the application specified a valid module handle in the hlnstString 

dwObjID 

Control ID. This is specified as a combination of one instance and one type flag. 
30 Applications use the DIDFT_GETINSTANCE and DIDFT_GETTYPE macros to decode this 
value to its constituent parts. 
guidlnstance 

Optional device instance GUID if a specific device is requested. Usually set to a 
NULL GUID by the application. 
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dwHow 

On input, this member is ignored. On output (when used with 
IDirectInputDevice8::BuildActionMap), this member indicates how the mapping was last 
achieved. 

5 If the mapping was a result of user configuration, device vendor default, device 

vendor game specific mapping, user specified preference for another game, application 
requested device, or Directlnput default mapping. 

Receives a value to indicate the actual mapping mechanism used by Directlnput in 
order to configure the action. The following values are defined: 

10 DIAH_ UNMAPPED 

This action is not mapped to a device control. This could be because the action does not 
apply to available device controls, or simply because it isn't currently assigned to a 
control. 

15 DIAHJJSERCONFIG 

This action was mapped to a device control by the user. 

DIAH_APPREQUESTED 

This action was mapped to a device control by the application. 

20 

DIAH_HWAPP 

This action was mapped to a device control by the device manufacturer, for the purpose of 
serving a particular game. 

25 DIAHJSWDEFA ULT 

This action was mapped to a device control by default, in accordance to the device 
manufacturer's recommendation to supporting a particular genre. 

DIAH_DEFAULT 

30 This is the default mapping for the device control. This represents Directlnpufs mappings 
in absence of any other default mapping information. 

DIAH_ERROR 

There was an error attempting to build an action map. This value can be set while calling 
35 IDirectInputDevice8::BuildActionMap, when an action cannot be matched to a control on 
the device (most likely a bad DIAH_APPMAPPED action). On set, actions marked 
invalid will be ignored. 
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DIACTIONFORMAT 

The DIACTIONFORMAT structure carries information about the calling application 
and acts as a container for an array of DIACTION structures that define a set of action-to- 
control mappings for a genre. This structure is used with the 
5 IDirectInputDevice8;:BuildActionMap and IDirectInputDevice8::SetActionMap methods. 

""typedef ""struct "_DIACTl6NFORMAT "{ " 

DWORD dwSize; 

DWORD dwAc t i onS i z e ; 

DWORD dwDataSize; 

1 0 DWORD dwNumAc t ion s ; 

LPDIACTION rgoAct ion ; 

GUID guidActionMap; 

DWORD dwGenre ; 

DWORD dwBuf f e r S i z e ; 

15 OPTIONAL LONG lAxisMin; // Relevant only to absolute axes and 

OPTIONAL LONG lAxisMax; // are otherwise ignored. 

OPTIONAL HINSTANCE hlnstString; 

FILETIME ftTimeStamp; 

DWORD dwCRC; 

20 TCHAR tszActionMap [MAX_PATH] ; 

} DIACTIONFORMAT, *LPDIACTIONFORMAT; 

dwSize 

Size of the DIACTIONFORMAT structure, in bytes. 
dwActionSize 

25 Size of the DIACTION structure, in bytes. 

dwDataSize 

The size of the device data that should be returned by the device for immediate device 
data, in bytes. This member should be dwNumActions multiplied by four. 

dwNumActions 
30 The number of actions in the rgo Action array. 

rgoAction 

Array of DIACTION structures, each of which describes how an action maps to a 
device semantic, and how the mapping information should be displayed to the user. 
guidActionMap 

35 Globally unique identifier (GUID) that identifies the action map. This enables device 

manufacturers to tune device mappings for a specific title. 
dwGenre 

Genre identifier for this set of action-to-control mappings. 
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dwBufferSize 

Buffer size to be set for the device. This value is internally set to the 
DIPROPBUFFERSIZE property on the device when the action map is applied by using 
IDirectInputDevice8::SetActionMap. This value is ignored by all other methods. 

5 lAxisMin and lAxisMax 

Minimum and maximum values for range of scaled data to be returned for all axes. 

These members are only used if DIANORANGE is set in dwFlags. The values are currently 

only valid for axis actions and should be set to zero for all other actions. These values are 

used as the IMin and IMax values to set the range property on an absolute axis when the 

10 action map is applied using E)irectInputDevice8::SetActionMap. These members are only 

valid for ranges on absolute axes, and are ignored otherwise. 

hlnstString 

Module handle for the module containing string resources for these actions. When 
used, the wResIdString members of the enclosed DIACTION structures can identify string 
1 5 resources in favor of explicit strings (specified in DIACTION JptszActionName). 
ftTimeStamp 

Time, reported as a Win32 FELETIME structure, at which this action map was last 
written to disk. 

Two special times are defined for action maps that apply to new devices and unused 
20 devices. New devices are those which have never before been enumerated for this application, 
and have never had an action map applied to them. Unused devices are those that have been 
enumerated for the application previously, but have never had an action map applied. New 
devices always have a timestamp with high and low DWORDs of the FILETIME structure set 
to OxFFFFFFFF; unused devices, have a time stamp with the high and low DWORDs set to 
25 0x00000000. The dinputh header file defines the DIAFTS NEWDEVICELOW and 
DIAFTS NEWDEVICEHIGH constants to identify new devices, and the 
DIAFTS_UNUSEDDEVICELOW and DIAFTS JJNUSEDDEVICEHIGH for devices 
previously enumerated, but never used by the application. 
dwCRC 

30 CRC for this action-to-control map. This value is used internally by Directlnput to 

determine when a set of mappings should be persisted to disk. 
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tszActionMap 

Null-terminated string, of maximum length MAX_PATH, identifying the friendly 
name for this action map. This string appears in the drop-down list box within the default 
configuration UI. 

5 

DICOLORSET 

The DICOLORSET structure contains colors that Directlnput uses to draw the 
configuration user interface. All colors are RGBA values. 

typedef struct _DICOLORSET{ " ' " " " 

10 DWORD dwSize; 

D3DCOLOR cTextFore; 

D3DCOLOR cTextHighlight; 

D3DCOLOR cCalloutLine; 

D3DCOLOR cCalloutHighlight; 
15 D3DCOLOR cBorder; 

D3DCOLOR cControlFill; 

D3DCOLOR cHighlightFill; 

D3DCOLOR cAreaFill; 
} DICOLORSET, *LPDICOLORSET; 

20 " " " " """" 

Members 

dwSize 

Size of the structure, in bytes. This must be initialized before the structure can be 

used. 

25 cTextFore 

Foreground text color. 

cTextHighlight 

Foreground color for highlighted text. 

cCalloutLine 

30 Color used to display callout lines within the UI. 

cCalloutHighlight 

Color used to display callout lines within the UL 
cBorder 

Border color, used to display lines around UI elements (tabs, buttons, etc). 
35 cControlFill 

Fill color for UI elements (tabs, buttons, etc). Text within UI elements is shown over 
this fill color. 
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cHighlightFill 

Fill color for highlighted UI elements (tabs, buttons, etc). Text within UI elements is 
shown over this fill color. 
cAreaFill 

5 Fill color for areas outside UI elements. 

Setting all members (except dwSize) to 0 causes the default UI to display a default 

color scheme. 

Text background color is always transparent. 

10 

DICONFIGUREDEVICESP ARAMS 

The DICONFIGUREDEVICESP ARAMS structure carries parameters used by the 
IDirectInput8::ConfigureDevices method. 

" typdef "struct "^DICONFIGUR 
15 DWORD dwSize; 

DWORD dwcUsers ; 

LPTSTR lptszUser Names ; 

DWORD dwcFormats; 

LPDIACTIONFORMAT IprgFormats ; 
20 HWND hwnd; 

DICOLORSET dies; 

IUnknown FAR * IpUnkDDS Targe t ; 
} DICONFIGUREDEVICESPARAMS, *LPDICONFIGUREDEVICESPARAMS_; 

25 dwSize 

Size of this structure, in bytes. 
dwcUsers 

Count of user names in the array at IptszUserNames. If the pointer at lptszUserNames 
is NULL (to indicate that the default user name should be used), the value in this member is 
30 ignored. If this value exceeds the number of names actually in the array at IptszUserNames, 
the method fails, returning DffiRRJNVALIDP ARAMS. 

Iptsz UserNames 

Buffer containing a series of null-terminated strings, the last of which is designated by 
a double-null terminator. 
35 If the application passes more names than the count indicates, only the names within 

the count are used. If an application specifies names that are different from the names 
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currently assigned to devices, ownership is revoked for all devices, a default name is created 
for the mismatched name, and the UI shows "(No User)" for all devices. 

dwcFormats 

Count of structures in the array at IprgFormats. 

IprgFormats 

Pointer to an array of DIACTIONFORMAT structures that contains action mapping 

information for each genre the game uses, to be utilized by the control panel. On input, each 

action-to-control mapping provides the desired genre semantics and the human-readable 

strings to be displayed as callouts for those semantics, as mapped to the installed devices. The 

configuration UI displays the genres in its drop-down list in the order they appear in the array. 
hwnd 

Window handle for the top-level window of the calling application. The member is 
needed only for applications that run in windowed mode. It is otherwise ignored. 
dies 

A DICOLORSET structure that describes the color scheme to be applied to the 
configuration user interface. 
IpUnkDDSTarget 

Pointer to the IUnknown interface for a DirectDraw or Direct3D target surface object 
for the configuration user interface. The device image is alpha-blended over the background 
surface onto the target surface. The object referred to by this interface must support either 
IDirect3DSurface, or the following versions of the DirectDraw surface interface: 
K)irectDrawSurface4, IDirectDrawSurface7. If the application is not providing a callback 
funtion, this member is ignored. 

DIDEYICEIMAGEINFO 

The DIDEVICEIMAGEINFO structure carries information required to display a 
device image, or an overlay image with a callout. This structure is used by the 
IDirectInputDevice8::GetImageInfo method, as an array contained within a 
DIDEVICEIMAGEINFOHEADER structure. 

typedef struct _DIDDEVICE IMAGE INFO "{"""" """" " ™ 

TCHAR tszImagePath[MAX_PATH] ; 
DWORD dwFlags; 
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10 



// These are valid if D ID IT_CONTROIj is present in dwFlags ~ " 
DWORD dwViewID; 
RECT rcOverlay; 
DWORD dwObjID; 
DWORD dwcValidPoints ; 

POINT rgptCalloutLine [5] ; 

RECT rcCal loutRec t ; 

DWORD dwTex t Al i gn ; 

} DIDEVICEIMAGEINFO, * LPDIDEVICEIMAGEINFO; 

tszImagePath 

Fully qualified path to the file that contains an image of the device. File format is 



given in dwFlags. If no image is available for the device, this member will be set to NULL. If 
so, the application is responsible for enumerating controls on the device and displaying a 
1 5 default listing of actions to device controls (similar to the method used by most applications 
before DirectX 8.0). 
dwFlags 

Flag that describes the intended use of the image. This member can be one of the 
following values. 

20 DIDIFT_ CONFIGURA TION 

The file is for use to display the current configuration of actions on the device. 
Overlay image coordinates are given relative to the upper left corner of the 
configuration image. 

25 DIDIFT_OVERLAY 

The file (if provided) is an overlay for a particular control on the configuration image. 
The dwOverlayOffset, rcOverlay, dwDevObjID, dicCalloutLine, dicCalloutRect, and 
dwTextAlign member are valid and contain data used to display the overlay and 
callout information for a single control on the device. If no file is provided (null path 
30 string), all other pertinent members are relevant except rcOverlay. 

dwViewID 

For device view images (DIDFTCONFIGURATION), this is the ID of the device 
view. For device control overlays (DIDFT_CONTROL), this value refers to the device view 
(by ID) over which an image and callout information should be displayed. 
35 Overlay 

Rectangle, using coordinates relative to the top-left pixel of the device configuration 
image, in which the overlay image should be painted. This member is only valid if the 
DIDIFT OVERLAY flag is present in dwFlags. 
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dwObjlD 

Control ID (as a combination of DEDFT * flags and an instance value) to which an 
overlay image corresponds for this device. This member is only valid if the 
DIDIFTOVERLAY flag is present in dwFlags. Applications use the 
5 DIDFT_GETINSTANCE and DK)FT_GETTYPE macros to decode this value to its 
constituent parts. 
dwcValidPts 

Number of points in the array at rgptCalloutLine which are valid. Points at index 

dwcValidPts should not be used. 

10 rgptCalloutLine 

Coordinates for the five points that describe a line with one to four segments that 

should be displayed as a callout to a game action string from a device control. This member is 

only valid if the DIDIFT OVERLAY flag is present in dwFlags. 

rcCalloutRect 

1 5 Rectangle in which the game action string should be displayed. If the string cannot fit 

within the rectangle, the application is responsible for handling clipping. This member is only 
valid if the DIDIFT OVERLAY flag is present in dwFlags. 

dwTextAlign 

One horizontal text-alignment flag, and one vertical text alignment flag. This member 
20 is only valid if the DIDIFT_OVERLAY flag is present in dwFlags. 

DID ALLEFT ALIGNED, DIDAL_CENTERED, DIDALRIGHTALIGNED 

The text within the rectangle described by rcCalloutRect should be (respectively) left 
aligned, centered, or right aligned. 

25 DIDAL JV1IDDLE, DIDALJTOPALIGNED, DIDAL BOTTOMALIGNED 

The text within the rectangle described by rcCalloutRect should be (respectively) top 
aligned, middle, or bottom aligned. 

DIDEVICEIMAGEINFOHEADER 

30 The DIDEVICEIMAGEINFOHEADER structure provides general information about 

device images, and provides a variable-length array of DIDEVICEIMAGE structures. 

typedef struct _D IDEVI CE IMAGE INFOHEADER { ~ ~ 

DWORD dwSize; 
DWORD dwSizelmagelnf o; 
35 DWORD dwc Views; 

DWORD dwcButtons; 
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DWORD dwcAxes ; 
DWORD dwBufferSize; 
DWORD dwBufferUsed; 

DIDEVICEIMAGEINFO *lprglmagelnf oArray ; 
5 } D IDEVICE IMAGE INFOHEADER, * LPD IDEVICE IMAGE INFOHEADER; 

dwSize 

Size of the DEDEVICEIMAGEINFOHEADER structure, in bytes. This must be 

initialized before the structure can be used. 

1 0 dwSizelmagelnfo 

Size of the DIDEVICEIMAGEINFO structure, in bytes. This must be initialized 

before the structure can be used. 

dwc Views 

Count of views for this device. Each represents a unique view of the device. 

15 dwcButtons 

Count of buttons for the device. 

dwcAxes 

Count of axes for the device. 

dwBufferSize 

20 Input only. Size, in bytes, of the buffer at lprglmageMo. When set to 0, the 

IDirectInputDevice8::GetImageInfo method returns the minimum buffer size required to hold 

information for all images in dwBufferUsed, producing no other output. 

dwBufferUsed 

Output only. Size, in bytes, of the memory used within the buffer at 
25 lprglmageDataArray. When dwBufferSize was set to zero, the 

IDirectInputDevice8::GetImageInfo method sets this member to the minimum size needed to 

hold information for all images. 

Iprglmagelnfo 

Buffer to be filled with an array of DIDEVICEIMAGE structures that describe all of 
30 the device images and views, overlay images, and callout-string coordinates. 

The buffer at Iprglmagelnfo must be large enough to hold all required image 
information structures. Applications can query for the required size by calling the 
IDirectInputDevice8::GetImageInfo method with the dwBufferSize member set to 0. After the 
35 call, dwBufferUsed contains amount of memory, in bytes, that was modified. 
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The dwcButtons and dwcAxes members contain data that can be retrieved elsewhere 
within Directlnput, but that would require additional code. These are included for ease-of-use 
for the application developer. 

5 DEVICE PROPERTIES 

DIPROP USERNAME 

The DIPROP JJSERNAME property retrieves the user name for a user currently 
assigned to a device, as a DPROPSTRING. This is a read-only property; user names are 
implicitly set by calling IDirectInputDevice8::SetActionMap. 

10 

DIPROPKEYNAME 

The DIPROP_KEYNAME property retrieves the localized key name for a keyboard 

key, as a DIPROPSTRING. This is a read-only property, key names cannot be changed. 

15 DIPROP SCANCODE 

The DP ROP JSCANCODE property retrieves the scan code for a keyboard key, as a 
DIPROPDWORD. This is a read-only property. 

DIPROP VIDPID 

20 The DIPROP JVIDPID property retrieves the vendor and product IDs from a device, 

as a DIPROPDWORD. The vendor ID is packed into the low word, and the product ID in 
high word. This is a read-only property. 

DIPROP UAPPDATA 

25 The DIPROPJUAPPDATA property sets and retrieves the application-defined value 

associated with an in-game action, as a DIPROPDWORD. This is a read/write property. 
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CALLBACK FUNCTIONS 

LPDICONFIGUREDEVICESCALLBACK 

LPDICONFIGUREDEVICESCALLBACK is a definition for an application-defined 
callback function called by IDirectInput8::ConfigureDevices. Directlnput copies image data 
from the Input configuration UI to the application-provided DirectDraw surface. It is the 
application's responsibility to display the surface. 

. typedef void "(FAR PASCAL * L PD I CONF I GUREDE VI )" ( " 
IUnknown FAR*, LPVOID 

J ; 

Parameters 

Par ami (Type: IUnknown FAR*) 

Address of an IUnknobwn interface for a DirectDraw or Direct3D surface object that 

contains the graphics for the configuration UI. This surface is originally passed to 

ConfigureDevices by the application. 

Param2 (Type: LPVOID) 

Address of application-defined data passed to lDirectInput8:: ConfigureDevices. 

Using this callback mechanism enables applications to add limited custom graphics 

and animations to the standard configuration UI. For complete control of device 

configuration, applications must use the Low-level UI APL 

LPDIENUMDEVICESBYSEMANTICSCB 

LPDIENUMDEVICESBYSEMANTICSCB is a definition for an application-defined 
callback function called by DDirectInput8::EnumDevicesBySemantics. 

25 typedef BOOL (FAR PASCAL * LPDIENUM)Ev¥cEBYSEM "(" " 

LPCDIDEVICEINSTANCE, LPDIRECTINPUTDEVICE8 , DWORD , DWORD, LPVOID 

) ; 

Paraml (Type: LPCDIDEVICEINSTANCE) 
30 Address of a DIDEVICEINSTANCE structure that describes an instance of a device. 

Param2 (Type: LPDIRECTINPUTDEVICE8) 

Pointer to the IDirectInputDevice8 interface for the device object described by this 

structure. 
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Param3 (Type: DWORD) 

Flags providing information about why the device is being enumerated. This can be a 

combination of any action-mapping flag, and one usage flag. At least one action-mapping flag 

will always be present. 

5 

Action Mapping Flags 

DIEDBS_MAPPEDPRI1 

The device is being enumerated because priority 1 actions can be mapped to the device. 

DIEDBSJMAPPEDPRI2 

10 The device is being enumerated because priority 2 actions can be mapped to the device. 



Usage Flags 

DIEDBSRECENTDEVICE 

The device is being enumerated because the commands described by the Action Mapping 
1 5 Flags were recently used. 

DIEDBSNEWDEVICE 

The device is being enumerated because the device was installed recently (sometime after 
the last set of commands were applied to another device). Devices described by this flag 
20 have not been used with this game before. 

Param4 (Type: DWORD) 

Number of devices, after this one, remaining to be enumerated. 

Param5 (Type: LPVOID) 

25 Application-defined data given to IDirectInput8: :EnumDevicesBySemantics 5 in the 

pAppData parameter. 

Applications may want to detect newly installed devices (DIEBS_NEWDEVICE) and 
automatically notify the user that a new device was detected. 

System devices (identified by the DIDEVTYPEMOUSE or 
30 DIDEVTYPE_KEYBOARD flags in the dwDevType member of Paraml) should probably 
always be polled for user input. 
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FILE FORMAT FOR ACTION TO CONTROL MAPS 

This section describes a file format that gaming-device manufacturers can use in order 
to express a rich set of capabilities to DirectX 8 titles. The genre definitions are found in the 
appendix. The definitions describe the language that allows game developers to exploit the 
capabilities of an input device. 

Our format is simply a variant of the .INI file format, which expresses game action to 
device control mappings. These files have the following format: 



10 [SectionNamel] 

VariableNameA=Value 1 
VariableNameB=Value2 

[SectionName] 
1 5 VariableNameA=Value3 



A device configuration file consists of the following parts: 

1 . List of supported devices and DirectX version 

20 2. Device Identification 

3. Device Images 

4. Control type list 

5. Control definitions 

6. Control overlay images 
25 7. Image (x, y) Offsets 

8. Genre definitions 

9. Game overrides 



30 



The file format allows for the inclusion of additional capabilities with future DirectX 
revisions. (For example future versions may allow a per genre or game calibration). 
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List of supported devices and DirectX version 

A single configuration file may contain mappings for multiple devices. The keyword 
Devices lists devices for which control to action maps are supplied. DirectXVersion indicates 
the version of the DirectX Genre mappings tables that are used. 

5 

Device Identification 

Vendor ID and Product ID can uniquely identify USB/HID devices. Legacy devices 
will be identified by the name of the device as found in the registry branch 
(HKLMA . ./MediaProperties/Joystick/OEM). The device vendor can provide a path to the 
10 device image. The device image will be used to display current action to control mappings 
and provide an easy mechanism for users to configure the device. 

Device Images 

A device may require multiple images in order to view and configure its controls. The 
15 keyword ImageFileName.# is used to specify multiple views of the device. The # field should 
begin with 0 and sequentially increment till all device images have been declared. 

Control type list 

Each device has a number of controls (axes, buttons, POV-s, etc). The keyword 
20 Controls lists the controls that a device supports. The device manufacturer can use any 
moniker to indicate identify a control. (Example: Xaxis, Thumb Button, etc). 



Control definitions 

This part defines how particular control name maps to the actual hardware 
25 (Button 1 [usage, usage page]). Each control on the device has its own section in the file. 
Values in the section describe how the control actually maps into the hardware. For most 
devices the HID Usage and UsagePage can uniquely identify a control. Additional keywords 
may be necessary for more sophisticated devices (TBD). 
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Non-USB devices use the Directlnput name to identify the control. For example: 
"Name=Button P\ Also, the Directlnput offset can be specified to identify the control, for 
example "Offset=12". (This is not to be confused with the image offsets.) 

The location of the control in the device image is indicated using offsets from the top- 
5 left of the image. 



Image offsets 

Vendors should provide offsets from the top left corner of the image to the point 
where the game labels will be drawn. Up to 10 points can be specified. The Mapper will draw 
10 a line through the 10 points and render the action label provided by the game at the last point. 

For example, "LineData.2-(l ? l) ? (2 ? 2) ? (3 ? 3)". The "Align" field specifies how to align 
the string. Valid values for Align are: C, L, R, T, B, TL, TR, BL, BR. Lastly, the CallOutMax 
field specifies the maximum size of the callout rectangle. This field describes the top-left and 
bottom-right points of a rectangle such as, "CallOutMax=(l 1,22),(33,44)". 



15 



20 



25 



Overlay Image 

In order to highlight the control selected by a user, the Mapper will overlay this image 
over the Device Image, when the control is selected. OverlayFileName.# is used to specify 
filename. The field OverlayFileName.# refers to ImageFileName.#. 

Genre definitions 

This is the part of the file that actually does the mapping between genres and 
semantics into the actual hardware. Each genre has its own section in the file. Each variable 
in the section represents the device control, and contains semantic value for that genre. 



[Directlnput] 

DirectXVersion=0x800 

Devices=SidewinderPrecisionPro, SidewinderJolt, SidewinderLedZep 



30 
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[SidewinderPrecisionPro] 



VendorID=0xl 
ProductID-0x4 



5 



Name=Sidewinder Precision Pro 
; Moniker for controls 



Controls=Xaxis,Yaxis,Twist,Slider31323334,B5363738,B9 
; Devices can support multiple images 



10 



; Max size of image is (423, 309) 
ImageFileName.O==Device0.png 
ImageFileName.l=Devicel .png 
ImageFileName.2=Device2.png 




5|C jjs S^C *fc 5j> jjc *Js SjC *]> #|* *l* 5jC SjC *J<E ?{C if* ijc jjc iji S|l *{C *J> 5j» 



20 



15 



[Xaxis] 

; Usages HID_USAGE_PAGE_GENERIC 
Usage=0xl 

;Usage Page = HID_USAGE__GENERIC_X 
UsagePage=0x30 
; Control name 
Name=X Axis 



;Dinput offset 
Offset-22 

;Line data in pixels from top left corner 

25 LineData.l=(124,24),(140,24),(190,50) 

; Overlay image: overlayed on top of ImageFile.x when control is selected 

OverlayFileName.l=XSelect.png 

Align. 1=L 

CalIOutMax.l=(250,50),(60,60) 

30 

[Yaxis] 



OverIayFileName.2=Yselectpng 

35 




*1» Oj- -lIp *!* *J> *i* »£■ %1» *i* »X» *I* *J* -X* *£* *i* *i» 4? Slf ^ 4f *|* 

*l* *(* *|» rj> JJ» ^ *t» *t» *t> ^ ^* ^» *f* *T* *T* *T* «v» *T> <f» "J* +j+ *j* *J* 



[SidewinderPrecision. Genre. 1 ] 



40 



; Xaxis is steering 
Xaxis=l 

; Yaxis is accelerate 
Yaxis=2 



[MTMLMacrol] 
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...TBD... 

y" — 1 J* <i* *1* *1# «Xc *1* ^ ^* *i» *!• *i* *A» •!* •3* «1* vfc* ^ <U Vt* *A* *J> *&* »A* *it» *j> *J> ^ *l* *S* *J* «J> »g* *l* «lf *£f 

[SidewinderPrecision.Application. {34C9990F-CBD7-1 1D2-AE0E- 
00C04FAEA83F} .Genre. 1 ] 

;Microsoft Monster Truck Madness vl, Genre Driving Sim 

Macros=MTMl .Macro 1,MTM1 .Macro2 
Xaxis=l 
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EXAMPLE SEMANTIC MAPPINGS 



Arcade - Platform Game 

Genre: 34 

DIAXIS_ARCADEP_MOVE:0x22008201 up / down 
5 DIAXIS_ARCADEP_LATERAL:0x22010202 left / right 
DIBUTTON_ARCADEP_JUMP:0x22000401 Jump 
DIBUTTON_ARCADEP_FIRE:0x22000402 Use weapon 
DIBUTTON_ARCADEP_CROUCH:0x22000403 Crouch 
DIBUTTON_ARCADEP_SPECIAL: 0x22000404 apply special move 
1 0 DIBUTTON_ARCADEP_SELECT:0x22000405 select special move 

DIBUTTON_ARCADEP_MENU:0x220004FE Pause - show menu options 
Priority2 Commands 

DIHATSWITCH_ARCADEP_VIEW:0x22004601 scroll view left / right / up / down 
DIBUTTON_ARCADEP_DEVICE:0x220044FD Show input device and controls 

15 Arcade- 2D 

Genre: 33 

DIAXIS_ARCADES_MOVE:0x21008201 up / down 

DIAXIS_ARCADES_LATERAL:0x21010202 left / right 
20 DffiUTTON_ARCADES_THROW:0x21000401 throw object 

DIBUTTON_ARCADES_CARRY:0x2 1000402 carry object 

DIBUTTON_ARCADES_ATTACK:0x21000403 attack 

DIBUTTON_ARCADES_SPECIAL:0x21000404 apply special move 

DIBUTTONARC ADESJSELECT : 0x2 1 000405 select special move 
25 DIBUTTON_ARCADES_MENU:0x210004FE Pause - show menu options 

Priority2 Commands 

DIHATSWITCH_ARCADES_VIEW:0x21004601 scroll view left / right / up / down 
DIBUTTON_ARCADES_DEVICE:0x210044FD Show input device and controls 

CAD - 2D Object Control 

30 

Genre: 35 

DIAXIS_2DCONTROL_MOVE:0x23008201 move view up / down 
DIAXIS_2DCONTROL_LATERAL:0x23010202 move view left / right 
DIAXIS_2DCONTROL_ZOOM:0x23050203 in / out 
35 DIBUTTON_2DCONTROL_SELECT:0x23000401 Select Object 

DIBUTTON_2DCONTROL_SPECIALl:0x23000402 do first special operation 
DIBUTTON_2DCONTROL_SPECIAL:0x23000403 Select special operation 
DIBUTTON_2DCONTROL_SPECIAL2:0x23000404 do second special operation 
DIBUTTON_2DCONTROL_MENU:0x230004FE Pause - show menu options 
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Priority2 Commands 

DfflATSWITCH_2DCONTROL_HATSWITCH:0x23004601 Hat switch 
DIAXIS_2DCONTROL_ROTATEZ:0x23024204 rotate view clockwise / 
counterclockwise 

5 DIBUTTON_2DCONTROL_DISPLAY:0x23004405 shows next on-screen display options 
DIBUTTON_2DCONTROL_DEVICE:0x230044FD Show input device and controls 

CAD - 3D Model Control 

Genre: 38 

10 DIAXIS_CADM_MOVE:0x26010201 move view up / down 

DIAXIS_CADM_LATERAL:0x26008202 move view left / right 

DIAXIS_CADM_ZOOM:0x26050203 in / out 

DIBUTTON_CADM_SELECT:0x26000401 Select Object 

DIBUTTON_CADM_SPECIALl:0x26000402 do first special operation 
1 5 DIBUTTON_CADM_SPECIAL:0x26000403 Select special operation 

DIBUTTON_CADM_SPECIAL2:0x26000404 do second special operation 

DIBUTTON_CADM_MENU:0x260004FE Pause - show menu options 

Priority2 Commands 

DIHATSWITCH_CADM_HATSWITCH:0x26004601 Hat switch 
20 DIAXIS_CADM_ROTATEX:0x26024204 rotate view forward or up / backward or down 
DIAXIS_CADM_ROTATEY:0x2602C205 rotate view left / right 
DIAXIS_CADM_ROTATEZ:0x26034206 rotate view clockwise / counterclockwise 
DIBUTTON_CADM_DISPLAY:0x26004405 shows next on-screen display options 
DIBUTTON_CADM_DEVICE:0x260044FD Show input device and controls 

25 

Having illustrated and described the principles of the illustrated embodiments, it will 
be apparent to those skilled in the art that the embodiments can be modified in arrangement 
and detail without departing from such principles. 

For example, although specific implementations of the API are illustrated, the API can 
30 easily be modified by changing parameters associated with the API methods. 

In view of the many possible embodiments, it will be recognized that the illustrated 
embodiments include only examples of the invention and should not be taken as a limitation 
on the scope of the invention. Rather, the invention is defined by the following claims. We 
therefore claim as the invention all such embodiments that come within the scope of these 
35 claims. 



